From 3b0fb9a86371099b1ca039f4cde4931d65281fcf Mon Sep 17 00:00:00 2001
From: Flop Butylkin <flopspm@gmail.com>
Date: Sun, 5 Jul 2026 20:52:02 +0200
Subject: [PATCH 1/4] Start new v0.11.0 development

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 packages/ksef-client-ts/CHANGELOG.md | 6 ++++++
 packages/ksef-client-ts/package.json | 2 +-
 2 files changed, 7 insertions(+), 1 deletion(-)

diff --git a/packages/ksef-client-ts/CHANGELOG.md b/packages/ksef-client-ts/CHANGELOG.md
index 4399122..19af62d 100644
--- a/packages/ksef-client-ts/CHANGELOG.md
+++ b/packages/ksef-client-ts/CHANGELOG.md
@@ -2,6 +2,12 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.11.0] - Unreleased
+
+### Added
+
+### Fixed
+
 ## [0.10.0] - 2026-06-15
 
 ### Changed (breaking)
diff --git a/packages/ksef-client-ts/package.json b/packages/ksef-client-ts/package.json
index e26d740..ef4d1c0 100644
--- a/packages/ksef-client-ts/package.json
+++ b/packages/ksef-client-ts/package.json
@@ -1,6 +1,6 @@
 {
   "name": "ksef-client-ts",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "TypeScript client for the Polish National e-Invoice System (KSeF) API",
   "type": "module",
   "sideEffects": false,

From 1454ccb872a12b3d096a6be9946dae25d1f0843a Mon Sep 17 00:00:00 2001
From: Flop Butylkin <flopspm@gmail.com>
Date: Sun, 5 Jul 2026 22:28:45 +0200
Subject: [PATCH 2/4] chore: regenerate OpenSpec tooling and expand .gitignore

- Regenerate openspec skills for claude/codex/cursor harnesses
- Add opsx command files for claude and cursor
- Ignore macOS, editor, log, and env/secret noise

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .claude/commands/opsx/apply.md                | 152 +++++++++++
 .claude/commands/opsx/archive.md              | 157 ++++++++++++
 .claude/commands/opsx/bulk-archive.md         | 242 ++++++++++++++++++
 .claude/commands/opsx/continue.md             | 114 +++++++++
 .claude/commands/opsx/explore.md              | 174 +++++++++++++
 .claude/commands/opsx/ff.md                   |  94 +++++++
 .claude/commands/opsx/new.md                  |  69 +++++
 .claude/commands/opsx/sync.md                 | 134 ++++++++++
 .claude/commands/opsx/verify.md               | 164 ++++++++++++
 .claude/skills/openspec-apply-change/SKILL.md |   2 +-
 .../skills/openspec-archive-change/SKILL.md   |   4 +-
 .../openspec-bulk-archive-change/SKILL.md     |   6 +-
 .../skills/openspec-continue-change/SKILL.md  |   2 +-
 .claude/skills/openspec-explore/SKILL.md      |  38 +--
 .claude/skills/openspec-ff-change/SKILL.md    |   2 +-
 .claude/skills/openspec-new-change/SKILL.md   |   2 +-
 .claude/skills/openspec-sync-specs/SKILL.md   |   2 +-
 .../skills/openspec-verify-change/SKILL.md    |   2 +-
 .codex/skills/openspec-apply-change/SKILL.md  |   2 +-
 .../skills/openspec-archive-change/SKILL.md   |   4 +-
 .../openspec-bulk-archive-change/SKILL.md     |   6 +-
 .../skills/openspec-continue-change/SKILL.md  |   2 +-
 .codex/skills/openspec-explore/SKILL.md       |  38 +--
 .codex/skills/openspec-ff-change/SKILL.md     |   2 +-
 .codex/skills/openspec-new-change/SKILL.md    |   2 +-
 .codex/skills/openspec-sync-specs/SKILL.md    |   2 +-
 .codex/skills/openspec-verify-change/SKILL.md |   2 +-
 .cursor/commands/opsx-apply.md                | 152 +++++++++++
 .cursor/commands/opsx-archive.md              | 157 ++++++++++++
 .cursor/commands/opsx-bulk-archive.md         | 242 ++++++++++++++++++
 .cursor/commands/opsx-continue.md             | 114 +++++++++
 .cursor/commands/opsx-explore.md              | 174 +++++++++++++
 .cursor/commands/opsx-ff.md                   |  94 +++++++
 .cursor/commands/opsx-new.md                  |  69 +++++
 .cursor/commands/opsx-sync.md                 | 134 ++++++++++
 .cursor/commands/opsx-verify.md               | 164 ++++++++++++
 .cursor/skills/openspec-apply-change/SKILL.md |   2 +-
 .../skills/openspec-archive-change/SKILL.md   |   4 +-
 .../openspec-bulk-archive-change/SKILL.md     |   6 +-
 .../skills/openspec-continue-change/SKILL.md  |   2 +-
 .cursor/skills/openspec-explore/SKILL.md      |  38 +--
 .cursor/skills/openspec-ff-change/SKILL.md    |   2 +-
 .cursor/skills/openspec-new-change/SKILL.md   |   2 +-
 .cursor/skills/openspec-sync-specs/SKILL.md   |   2 +-
 .../skills/openspec-verify-change/SKILL.md    |   2 +-
 .gitignore                                    |  19 ++
 46 files changed, 2712 insertions(+), 87 deletions(-)
 create mode 100644 .claude/commands/opsx/apply.md
 create mode 100644 .claude/commands/opsx/archive.md
 create mode 100644 .claude/commands/opsx/bulk-archive.md
 create mode 100644 .claude/commands/opsx/continue.md
 create mode 100644 .claude/commands/opsx/explore.md
 create mode 100644 .claude/commands/opsx/ff.md
 create mode 100644 .claude/commands/opsx/new.md
 create mode 100644 .claude/commands/opsx/sync.md
 create mode 100644 .claude/commands/opsx/verify.md
 create mode 100644 .cursor/commands/opsx-apply.md
 create mode 100644 .cursor/commands/opsx-archive.md
 create mode 100644 .cursor/commands/opsx-bulk-archive.md
 create mode 100644 .cursor/commands/opsx-continue.md
 create mode 100644 .cursor/commands/opsx-explore.md
 create mode 100644 .cursor/commands/opsx-ff.md
 create mode 100644 .cursor/commands/opsx-new.md
 create mode 100644 .cursor/commands/opsx-sync.md
 create mode 100644 .cursor/commands/opsx-verify.md

diff --git a/.claude/commands/opsx/apply.md b/.claude/commands/opsx/apply.md
new file mode 100644
index 0000000..bf23721
--- /dev/null
+++ b/.claude/commands/opsx/apply.md
@@ -0,0 +1,152 @@
+---
+name: "OPSX: Apply"
+description: Implement tasks from an OpenSpec change (Experimental)
+category: Workflow
+tags: [workflow, artifacts, experimental]
+---
+
+Implement tasks from an OpenSpec change.
+
+**Input**: Optionally specify a change name (e.g., `/opsx:apply add-auth`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **Select the change**
+
+   If a name is provided, use it. Otherwise:
+   - Infer from conversation context if the user mentioned a change
+   - Auto-select if only one active change exists
+   - If ambiguous, run `openspec list --json` to get available changes and use the **AskUserQuestion tool** to let the user select
+
+   Always announce: "Using change: <name>" and how to override (e.g., `/opsx:apply <other>`).
+
+2. **Check status to understand the schema**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used (e.g., "spec-driven")
+   - Which artifact contains the tasks (typically "tasks" for spec-driven, check status for others)
+
+3. **Get apply instructions**
+
+   ```bash
+   openspec instructions apply --change "<name>" --json
+   ```
+
+   This returns:
+   - Context file paths (varies by schema)
+   - Progress (total, complete, remaining)
+   - Task list with status
+   - Dynamic instruction based on current state
+
+   **Handle states:**
+   - If `state: "blocked"` (missing artifacts): show message, suggest using `/opsx:continue`
+   - If `state: "all_done"`: congratulate, suggest archive
+   - Otherwise: proceed to implementation
+
+4. **Read context files**
+
+   Read the files listed in `contextFiles` from the apply instructions output.
+   The files depend on the schema being used:
+   - **spec-driven**: proposal, specs, design, tasks
+   - Other schemas: follow the contextFiles from CLI output
+
+5. **Show current progress**
+
+   Display:
+   - Schema being used
+   - Progress: "N/M tasks complete"
+   - Remaining tasks overview
+   - Dynamic instruction from CLI
+
+6. **Implement tasks (loop until done or blocked)**
+
+   For each pending task:
+   - Show which task is being worked on
+   - Make the code changes required
+   - Keep changes minimal and focused
+   - Mark task complete in the tasks file: `- [ ]` → `- [x]`
+   - Continue to next task
+
+   **Pause if:**
+   - Task is unclear → ask for clarification
+   - Implementation reveals a design issue → suggest updating artifacts
+   - Error or blocker encountered → report and wait for guidance
+   - User interrupts
+
+7. **On completion or pause, show status**
+
+   Display:
+   - Tasks completed this session
+   - Overall progress: "N/M tasks complete"
+   - If all done: suggest archive
+   - If paused: explain why and wait for guidance
+
+**Output During Implementation**
+
+```
+## Implementing: <change-name> (schema: <schema-name>)
+
+Working on task 3/7: <task description>
+[...implementation happening...]
+✓ Task complete
+
+Working on task 4/7: <task description>
+[...implementation happening...]
+✓ Task complete
+```
+
+**Output On Completion**
+
+```
+## Implementation Complete
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Progress:** 7/7 tasks complete ✓
+
+### Completed This Session
+- [x] Task 1
+- [x] Task 2
+...
+
+All tasks complete! You can archive this change with `/opsx:archive`.
+```
+
+**Output On Pause (Issue Encountered)**
+
+```
+## Implementation Paused
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Progress:** 4/7 tasks complete
+
+### Issue Encountered
+<description of the issue>
+
+**Options:**
+1. <option 1>
+2. <option 2>
+3. Other approach
+
+What would you like to do?
+```
+
+**Guardrails**
+- Keep going through tasks until done or blocked
+- Always read context files before starting (from the apply instructions output)
+- If task is ambiguous, pause and ask before implementing
+- If implementation reveals issues, pause and suggest artifact updates
+- Keep code changes minimal and scoped to each task
+- Update task checkbox immediately after completing each task
+- Pause on errors, blockers, or unclear requirements - don't guess
+- Use contextFiles from CLI output, don't assume specific file names
+
+**Fluid Workflow Integration**
+
+This skill supports the "actions on a change" model:
+
+- **Can be invoked anytime**: Before all artifacts are done (if tasks exist), after partial implementation, interleaved with other actions
+- **Allows artifact updates**: If implementation reveals design issues, suggest updating artifacts - not phase-locked, work fluidly
diff --git a/.claude/commands/opsx/archive.md b/.claude/commands/opsx/archive.md
new file mode 100644
index 0000000..7275c85
--- /dev/null
+++ b/.claude/commands/opsx/archive.md
@@ -0,0 +1,157 @@
+---
+name: "OPSX: Archive"
+description: Archive a completed change in the experimental workflow
+category: Workflow
+tags: [workflow, archive, experimental]
+---
+
+Archive a completed change in the experimental workflow.
+
+**Input**: Optionally specify a change name after `/opsx:archive` (e.g., `/opsx:archive add-auth`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **If no change name provided, prompt for selection**
+
+   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+
+   Show only active changes (not already archived).
+   Include the schema used for each change if available.
+
+   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
+
+2. **Check artifact completion status**
+
+   Run `openspec status --change "<name>" --json` to check artifact completion.
+
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used
+   - `artifacts`: List of artifacts with their status (`done` or other)
+
+   **If any artifacts are not `done`:**
+   - Display warning listing incomplete artifacts
+   - Prompt user for confirmation to continue
+   - Proceed if user confirms
+
+3. **Check task completion status**
+
+   Read the tasks file (typically `tasks.md`) to check for incomplete tasks.
+
+   Count tasks marked with `- [ ]` (incomplete) vs `- [x]` (complete).
+
+   **If incomplete tasks found:**
+   - Display warning showing count of incomplete tasks
+   - Prompt user for confirmation to continue
+   - Proceed if user confirms
+
+   **If no tasks file exists:** Proceed without task-related warning.
+
+4. **Assess delta spec sync state**
+
+   Check for delta specs at `openspec/changes/<name>/specs/`. If none exist, proceed without sync prompt.
+
+   **If delta specs exist:**
+   - Compare each delta spec with its corresponding main spec at `openspec/specs/<capability>/spec.md`
+   - Determine what changes would be applied (adds, modifications, removals, renames)
+   - Show a combined summary before prompting
+
+   **Prompt options:**
+   - If changes needed: "Sync now (recommended)", "Archive without syncing"
+   - If already synced: "Archive now", "Sync anyway", "Cancel"
+
+   If user chooses sync, execute `/opsx:sync` logic. Proceed to archive regardless of choice.
+
+5. **Perform the archive**
+
+   Create the archive directory if it doesn't exist:
+   ```bash
+   mkdir -p openspec/changes/archive
+   ```
+
+   Generate target name using current date: `YYYY-MM-DD-<change-name>`
+
+   **Check if target already exists:**
+   - If yes: Fail with error, suggest renaming existing archive or using different date
+   - If no: Move the change directory to archive
+
+   ```bash
+   mv openspec/changes/<name> openspec/changes/archive/YYYY-MM-DD-<name>
+   ```
+
+6. **Display summary**
+
+   Show archive completion summary including:
+   - Change name
+   - Schema that was used
+   - Archive location
+   - Spec sync status (synced / sync skipped / no delta specs)
+   - Note about any warnings (incomplete artifacts/tasks)
+
+**Output On Success**
+
+```
+## Archive Complete
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Specs:** ✓ Synced to main specs
+
+All artifacts complete. All tasks complete.
+```
+
+**Output On Success (No Delta Specs)**
+
+```
+## Archive Complete
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Specs:** No delta specs
+
+All artifacts complete. All tasks complete.
+```
+
+**Output On Success With Warnings**
+
+```
+## Archive Complete (with warnings)
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Specs:** Sync skipped (user chose to skip)
+
+**Warnings:**
+- Archived with 2 incomplete artifacts
+- Archived with 3 incomplete tasks
+- Delta spec sync was skipped (user chose to skip)
+
+Review the archive if this was not intentional.
+```
+
+**Output On Error (Archive Exists)**
+
+```
+## Archive Failed
+
+**Change:** <change-name>
+**Target:** openspec/changes/archive/YYYY-MM-DD-<name>/
+
+Target archive directory already exists.
+
+**Options:**
+1. Rename the existing archive
+2. Delete the existing archive if it's a duplicate
+3. Wait until a different date to archive
+```
+
+**Guardrails**
+- Always prompt for change selection if not provided
+- Use artifact graph (openspec status --json) for completion checking
+- Don't block archive on warnings - just inform and confirm
+- Preserve .openspec.yaml when moving to archive (it moves with the directory)
+- Show clear summary of what happened
+- If sync is requested, use /opsx:sync approach (agent-driven)
+- If delta specs exist, always run the sync assessment and show the combined summary before prompting
diff --git a/.claude/commands/opsx/bulk-archive.md b/.claude/commands/opsx/bulk-archive.md
new file mode 100644
index 0000000..b700261
--- /dev/null
+++ b/.claude/commands/opsx/bulk-archive.md
@@ -0,0 +1,242 @@
+---
+name: "OPSX: Bulk Archive"
+description: Archive multiple completed changes at once
+category: Workflow
+tags: [workflow, archive, experimental, bulk]
+---
+
+Archive multiple completed changes in a single operation.
+
+This skill allows you to batch-archive changes, handling spec conflicts intelligently by checking the codebase to determine what's actually implemented.
+
+**Input**: None required (prompts for selection)
+
+**Steps**
+
+1. **Get active changes**
+
+   Run `openspec list --json` to get all active changes.
+
+   If no active changes exist, inform user and stop.
+
+2. **Prompt for change selection**
+
+   Use **AskUserQuestion tool** with multi-select to let user choose changes:
+   - Show each change with its schema
+   - Include an option for "All changes"
+   - Allow any number of selections (1+ works, 2+ is the typical use case)
+
+   **IMPORTANT**: Do NOT auto-select. Always let the user choose.
+
+3. **Batch validation - gather status for all selected changes**
+
+   For each selected change, collect:
+
+   a. **Artifact status** - Run `openspec status --change "<name>" --json`
+      - Parse `schemaName` and `artifacts` list
+      - Note which artifacts are `done` vs other states
+
+   b. **Task completion** - Read `openspec/changes/<name>/tasks.md`
+      - Count `- [ ]` (incomplete) vs `- [x]` (complete)
+      - If no tasks file exists, note as "No tasks"
+
+   c. **Delta specs** - Check `openspec/changes/<name>/specs/` directory
+      - List which capability specs exist
+      - For each, extract requirement names (lines matching `### Requirement: <name>`)
+
+4. **Detect spec conflicts**
+
+   Build a map of `capability -> [changes that touch it]`:
+
+   ```
+   auth -> [change-a, change-b]  <- CONFLICT (2+ changes)
+   api  -> [change-c]            <- OK (only 1 change)
+   ```
+
+   A conflict exists when 2+ selected changes have delta specs for the same capability.
+
+5. **Resolve conflicts agentically**
+
+   **For each conflict**, investigate the codebase:
+
+   a. **Read the delta specs** from each conflicting change to understand what each claims to add/modify
+
+   b. **Search the codebase** for implementation evidence:
+      - Look for code implementing requirements from each delta spec
+      - Check for related files, functions, or tests
+
+   c. **Determine resolution**:
+      - If only one change is actually implemented -> sync that one's specs
+      - If both implemented -> apply in chronological order (older first, newer overwrites)
+      - If neither implemented -> skip spec sync, warn user
+
+   d. **Record resolution** for each conflict:
+      - Which change's specs to apply
+      - In what order (if both)
+      - Rationale (what was found in codebase)
+
+6. **Show consolidated status table**
+
+   Display a table summarizing all changes:
+
+   ```
+   | Change               | Artifacts | Tasks | Specs   | Conflicts | Status |
+   |---------------------|-----------|-------|---------|-----------|--------|
+   | schema-management   | Done      | 5/5   | 2 delta | None      | Ready  |
+   | project-config      | Done      | 3/3   | 1 delta | None      | Ready  |
+   | add-oauth           | Done      | 4/4   | 1 delta | auth (!)  | Ready* |
+   | add-verify-skill    | 1 left    | 2/5   | None    | None      | Warn   |
+   ```
+
+   For conflicts, show the resolution:
+   ```
+   * Conflict resolution:
+     - auth spec: Will apply add-oauth then add-jwt (both implemented, chronological order)
+   ```
+
+   For incomplete changes, show warnings:
+   ```
+   Warnings:
+   - add-verify-skill: 1 incomplete artifact, 3 incomplete tasks
+   ```
+
+7. **Confirm batch operation**
+
+   Use **AskUserQuestion tool** with a single confirmation:
+
+   - "Archive N changes?" with options based on status
+   - Options might include:
+     - "Archive all N changes"
+     - "Archive only N ready changes (skip incomplete)"
+     - "Cancel"
+
+   If there are incomplete changes, make clear they'll be archived with warnings.
+
+8. **Execute archive for each confirmed change**
+
+   Process changes in the determined order (respecting conflict resolution):
+
+   a. **Sync specs** if delta specs exist:
+      - Use the openspec-sync-specs approach (agent-driven intelligent merge)
+      - For conflicts, apply in resolved order
+      - Track if sync was done
+
+   b. **Perform the archive**:
+      ```bash
+      mkdir -p openspec/changes/archive
+      mv openspec/changes/<name> openspec/changes/archive/YYYY-MM-DD-<name>
+      ```
+
+   c. **Track outcome** for each change:
+      - Success: archived successfully
+      - Failed: error during archive (record error)
+      - Skipped: user chose not to archive (if applicable)
+
+9. **Display summary**
+
+   Show final results:
+
+   ```
+   ## Bulk Archive Complete
+
+   Archived 3 changes:
+   - schema-management-cli -> archive/2026-01-19-schema-management-cli/
+   - project-config -> archive/2026-01-19-project-config/
+   - add-oauth -> archive/2026-01-19-add-oauth/
+
+   Skipped 1 change:
+   - add-verify-skill (user chose not to archive incomplete)
+
+   Spec sync summary:
+   - 4 delta specs synced to main specs
+   - 1 conflict resolved (auth: applied both in chronological order)
+   ```
+
+   If any failures:
+   ```
+   Failed 1 change:
+   - some-change: Archive directory already exists
+   ```
+
+**Conflict Resolution Examples**
+
+Example 1: Only one implemented
+```
+Conflict: specs/auth/spec.md touched by [add-oauth, add-jwt]
+
+Checking add-oauth:
+- Delta adds "OAuth Provider Integration" requirement
+- Searching codebase... found src/auth/oauth.ts implementing OAuth flow
+
+Checking add-jwt:
+- Delta adds "JWT Token Handling" requirement
+- Searching codebase... no JWT implementation found
+
+Resolution: Only add-oauth is implemented. Will sync add-oauth specs only.
+```
+
+Example 2: Both implemented
+```
+Conflict: specs/api/spec.md touched by [add-rest-api, add-graphql]
+
+Checking add-rest-api (created 2026-01-10):
+- Delta adds "REST Endpoints" requirement
+- Searching codebase... found src/api/rest.ts
+
+Checking add-graphql (created 2026-01-15):
+- Delta adds "GraphQL Schema" requirement
+- Searching codebase... found src/api/graphql.ts
+
+Resolution: Both implemented. Will apply add-rest-api specs first,
+then add-graphql specs (chronological order, newer takes precedence).
+```
+
+**Output On Success**
+
+```
+## Bulk Archive Complete
+
+Archived N changes:
+- <change-1> -> archive/YYYY-MM-DD-<change-1>/
+- <change-2> -> archive/YYYY-MM-DD-<change-2>/
+
+Spec sync summary:
+- N delta specs synced to main specs
+- No conflicts (or: M conflicts resolved)
+```
+
+**Output On Partial Success**
+
+```
+## Bulk Archive Complete (partial)
+
+Archived N changes:
+- <change-1> -> archive/YYYY-MM-DD-<change-1>/
+
+Skipped M changes:
+- <change-2> (user chose not to archive incomplete)
+
+Failed K changes:
+- <change-3>: Archive directory already exists
+```
+
+**Output When No Changes**
+
+```
+## No Changes to Archive
+
+No active changes found. Use `/opsx:new` to create a new change.
+```
+
+**Guardrails**
+- Allow any number of changes (1+ is fine, 2+ is the typical use case)
+- Always prompt for selection, never auto-select
+- Detect spec conflicts early and resolve by checking codebase
+- When both changes are implemented, apply specs in chronological order
+- Skip spec sync only when implementation is missing (warn user)
+- Show clear per-change status before confirming
+- Use single confirmation for entire batch
+- Track and report all outcomes (success/skip/fail)
+- Preserve .openspec.yaml when moving to archive
+- Archive directory target uses current date: YYYY-MM-DD-<name>
+- If archive target exists, fail that change but continue with others
diff --git a/.claude/commands/opsx/continue.md b/.claude/commands/opsx/continue.md
new file mode 100644
index 0000000..af255c6
--- /dev/null
+++ b/.claude/commands/opsx/continue.md
@@ -0,0 +1,114 @@
+---
+name: "OPSX: Continue"
+description: Continue working on a change - create the next artifact (Experimental)
+category: Workflow
+tags: [workflow, artifacts, experimental]
+---
+
+Continue working on a change by creating the next artifact.
+
+**Input**: Optionally specify a change name after `/opsx:continue` (e.g., `/opsx:continue add-auth`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **If no change name provided, prompt for selection**
+
+   Run `openspec list --json` to get available changes sorted by most recently modified. Then use the **AskUserQuestion tool** to let the user select which change to work on.
+
+   Present the top 3-4 most recently modified changes as options, showing:
+   - Change name
+   - Schema (from `schema` field if present, otherwise "spec-driven")
+   - Status (e.g., "0/5 tasks", "complete", "no tasks")
+   - How recently it was modified (from `lastModified` field)
+
+   Mark the most recently modified change as "(Recommended)" since it's likely what the user wants to continue.
+
+   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
+
+2. **Check current status**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to understand current state. The response includes:
+   - `schemaName`: The workflow schema being used (e.g., "spec-driven")
+   - `artifacts`: Array of artifacts with their status ("done", "ready", "blocked")
+   - `isComplete`: Boolean indicating if all artifacts are complete
+
+3. **Act based on status**:
+
+   ---
+
+   **If all artifacts are complete (`isComplete: true`)**:
+   - Congratulate the user
+   - Show final status including the schema used
+   - Suggest: "All artifacts created! You can now implement this change with `/opsx:apply` or archive it with `/opsx:archive`."
+   - STOP
+
+   ---
+
+   **If artifacts are ready to create** (status shows artifacts with `status: "ready"`):
+   - Pick the FIRST artifact with `status: "ready"` from the status output
+   - Get its instructions:
+     ```bash
+     openspec instructions <artifact-id> --change "<name>" --json
+     ```
+   - Parse the JSON. The key fields are:
+     - `context`: Project background (constraints for you - do NOT include in output)
+     - `rules`: Artifact-specific rules (constraints for you - do NOT include in output)
+     - `template`: The structure to use for your output file
+     - `instruction`: Schema-specific guidance
+     - `outputPath`: Where to write the artifact
+     - `dependencies`: Completed artifacts to read for context
+   - **Create the artifact file**:
+     - Read any completed dependency files for context
+     - Use `template` as the structure - fill in its sections
+     - Apply `context` and `rules` as constraints when writing - but do NOT copy them into the file
+     - Write to the output path specified in instructions
+   - Show what was created and what's now unlocked
+   - STOP after creating ONE artifact
+
+   ---
+
+   **If no artifacts are ready (all blocked)**:
+   - This shouldn't happen with a valid schema
+   - Show status and suggest checking for issues
+
+4. **After creating an artifact, show progress**
+   ```bash
+   openspec status --change "<name>"
+   ```
+
+**Output**
+
+After each invocation, show:
+- Which artifact was created
+- Schema workflow being used
+- Current progress (N/M complete)
+- What artifacts are now unlocked
+- Prompt: "Run `/opsx:continue` to create the next artifact"
+
+**Artifact Creation Guidelines**
+
+The artifact types and their purpose depend on the schema. Use the `instruction` field from the instructions output to understand what to create.
+
+Common artifact patterns:
+
+**spec-driven schema** (proposal → specs → design → tasks):
+- **proposal.md**: Ask user about the change if not clear. Fill in Why, What Changes, Capabilities, Impact.
+  - The Capabilities section is critical - each capability listed will need a spec file.
+- **specs/<capability>/spec.md**: Create one spec per capability listed in the proposal's Capabilities section (use the capability name, not the change name).
+- **design.md**: Document technical decisions, architecture, and implementation approach.
+- **tasks.md**: Break down implementation into checkboxed tasks.
+
+For other schemas, follow the `instruction` field from the CLI output.
+
+**Guardrails**
+- Create ONE artifact per invocation
+- Always read dependency artifacts before creating a new one
+- Never skip artifacts or create out of order
+- If context is unclear, ask the user before creating
+- Verify the artifact file exists after writing before marking progress
+- Use the schema's artifact sequence, don't assume specific artifact names
+- **IMPORTANT**: `context` and `rules` are constraints for YOU, not content for the file
+  - Do NOT copy `<context>`, `<rules>`, `<project_context>` blocks into the artifact
+  - These guide what you write, but should never appear in the output
diff --git a/.claude/commands/opsx/explore.md b/.claude/commands/opsx/explore.md
new file mode 100644
index 0000000..202566b
--- /dev/null
+++ b/.claude/commands/opsx/explore.md
@@ -0,0 +1,174 @@
+---
+name: "OPSX: Explore"
+description: "Enter explore mode - think through ideas, investigate problems, clarify requirements"
+category: Workflow
+tags: [workflow, explore, experimental, thinking]
+---
+
+Enter explore mode. Think deeply. Visualize freely. Follow the conversation wherever it goes.
+
+**IMPORTANT: Explore mode is for thinking, not implementing.** You may read files, search code, and investigate the codebase, but you must NEVER write code or implement features. If the user asks you to implement something, remind them to exit explore mode first (e.g., start a change with `/opsx:new` or `/opsx:ff`). You MAY create OpenSpec artifacts (proposals, designs, specs) if the user asks—that's capturing thinking, not implementing.
+
+**This is a stance, not a workflow.** There are no fixed steps, no required sequence, no mandatory outputs. You're a thinking partner helping the user explore.
+
+**Input**: The argument after `/opsx:explore` is whatever the user wants to think about. Could be:
+- A vague idea: "real-time collaboration"
+- A specific problem: "the auth system is getting unwieldy"
+- A change name: "add-dark-mode" (to explore in context of that change)
+- A comparison: "postgres vs sqlite for this"
+- Nothing (just enter explore mode)
+
+---
+
+## The Stance
+
+- **Curious, not prescriptive** - Ask questions that emerge naturally, don't follow a script
+- **Open threads, not interrogations** - Surface multiple interesting directions and let the user follow what resonates. Don't funnel them through a single path of questions.
+- **Visual** - Use ASCII diagrams liberally when they'd help clarify thinking
+- **Adaptive** - Follow interesting threads, pivot when new information emerges
+- **Patient** - Don't rush to conclusions, let the shape of the problem emerge
+- **Grounded** - Explore the actual codebase when relevant, don't just theorize
+
+---
+
+## What You Might Do
+
+Depending on what the user brings, you might:
+
+**Explore the problem space**
+- Ask clarifying questions that emerge from what they said
+- Challenge assumptions
+- Reframe the problem
+- Find analogies
+
+**Investigate the codebase**
+- Map existing architecture relevant to the discussion
+- Find integration points
+- Identify patterns already in use
+- Surface hidden complexity
+
+**Compare options**
+- Brainstorm multiple approaches
+- Build comparison tables
+- Sketch tradeoffs
+- Recommend a path (if asked)
+
+**Visualize**
+```
+┌─────────────────────────────────────────┐
+│     Use ASCII diagrams liberally        │
+├─────────────────────────────────────────┤
+│                                         │
+│   ┌────────┐         ┌────────┐        │
+│   │ State  │────────▶│ State  │        │
+│   │   A    │         │   B    │        │
+│   └────────┘         └────────┘        │
+│                                         │
+│   System diagrams, state machines,      │
+│   data flows, architecture sketches,    │
+│   dependency graphs, comparison tables  │
+│                                         │
+└─────────────────────────────────────────┘
+```
+
+**Surface risks and unknowns**
+- Identify what could go wrong
+- Find gaps in understanding
+- Suggest spikes or investigations
+
+---
+
+## OpenSpec Awareness
+
+You have full context of the OpenSpec system. Use it naturally, don't force it.
+
+### Check for context
+
+At the start, quickly check what exists:
+```bash
+openspec list --json
+```
+
+This tells you:
+- If there are active changes
+- Their names, schemas, and status
+- What the user might be working on
+
+If the user mentioned a specific change name, read its artifacts for context.
+
+### When no change exists
+
+Think freely. When insights crystallize, you might offer:
+
+- "This feels solid enough to start a change. Want me to create one?"
+  → Can transition to `/opsx:new` or `/opsx:ff`
+- Or keep exploring - no pressure to formalize
+
+### When a change exists
+
+If the user mentions a change or you detect one is relevant:
+
+1. **Read existing artifacts for context**
+   - `openspec/changes/<name>/proposal.md`
+   - `openspec/changes/<name>/design.md`
+   - `openspec/changes/<name>/tasks.md`
+   - etc.
+
+2. **Reference them naturally in conversation**
+   - "Your design mentions using Redis, but we just realized SQLite fits better..."
+   - "The proposal scopes this to premium users, but we're now thinking everyone..."
+
+3. **Offer to capture when decisions are made**
+
+   | Insight Type | Where to Capture |
+   |--------------|------------------|
+   | New requirement discovered | `specs/<capability>/spec.md` |
+   | Requirement changed | `specs/<capability>/spec.md` |
+   | Design decision made | `design.md` |
+   | Scope changed | `proposal.md` |
+   | New work identified | `tasks.md` |
+   | Assumption invalidated | Relevant artifact |
+
+   Example offers:
+   - "That's a design decision. Capture it in design.md?"
+   - "This is a new requirement. Add it to specs?"
+   - "This changes scope. Update the proposal?"
+
+4. **The user decides** - Offer and move on. Don't pressure. Don't auto-capture.
+
+---
+
+## What You Don't Have To Do
+
+- Follow a script
+- Ask the same questions every time
+- Produce a specific artifact
+- Reach a conclusion
+- Stay on topic if a tangent is valuable
+- Be brief (this is thinking time)
+
+---
+
+## Ending Discovery
+
+There's no required ending. Discovery might:
+
+- **Flow into action**: "Ready to start? `/opsx:new` or `/opsx:ff`"
+- **Result in artifact updates**: "Updated design.md with these decisions"
+- **Just provide clarity**: User has what they need, moves on
+- **Continue later**: "We can pick this up anytime"
+
+When things crystallize, you might offer a summary - but it's optional. Sometimes the thinking IS the value.
+
+---
+
+## Guardrails
+
+- **Don't implement** - Never write code or implement features. Creating OpenSpec artifacts is fine, writing application code is not.
+- **Don't fake understanding** - If something is unclear, dig deeper
+- **Don't rush** - Discovery is thinking time, not task time
+- **Don't force structure** - Let patterns emerge naturally
+- **Don't auto-capture** - Offer to save insights, don't just do it
+- **Do visualize** - A good diagram is worth many paragraphs
+- **Do explore the codebase** - Ground discussions in reality
+- **Do question assumptions** - Including the user's and your own
diff --git a/.claude/commands/opsx/ff.md b/.claude/commands/opsx/ff.md
new file mode 100644
index 0000000..bea9d61
--- /dev/null
+++ b/.claude/commands/opsx/ff.md
@@ -0,0 +1,94 @@
+---
+name: "OPSX: Fast Forward"
+description: Create a change and generate all artifacts needed for implementation in one go
+category: Workflow
+tags: [workflow, artifacts, experimental]
+---
+
+Fast-forward through artifact creation - generate everything needed to start implementation.
+
+**Input**: The argument after `/opsx:ff` is the change name (kebab-case), OR a description of what the user wants to build.
+
+**Steps**
+
+1. **If no input provided, ask what they want to build**
+
+   Use the **AskUserQuestion tool** (open-ended, no preset options) to ask:
+   > "What change do you want to work on? Describe what you want to build or fix."
+
+   From their description, derive a kebab-case name (e.g., "add user authentication" → `add-user-auth`).
+
+   **IMPORTANT**: Do NOT proceed without understanding what the user wants to build.
+
+2. **Create the change directory**
+   ```bash
+   openspec new change "<name>"
+   ```
+   This creates a scaffolded change at `openspec/changes/<name>/`.
+
+3. **Get the artifact build order**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to get:
+   - `applyRequires`: array of artifact IDs needed before implementation (e.g., `["tasks"]`)
+   - `artifacts`: list of all artifacts with their status and dependencies
+
+4. **Create artifacts in sequence until apply-ready**
+
+   Use the **TodoWrite tool** to track progress through the artifacts.
+
+   Loop through artifacts in dependency order (artifacts with no pending dependencies first):
+
+   a. **For each artifact that is `ready` (dependencies satisfied)**:
+      - Get instructions:
+        ```bash
+        openspec instructions <artifact-id> --change "<name>" --json
+        ```
+      - The instructions JSON includes:
+        - `context`: Project background (constraints for you - do NOT include in output)
+        - `rules`: Artifact-specific rules (constraints for you - do NOT include in output)
+        - `template`: The structure to use for your output file
+        - `instruction`: Schema-specific guidance for this artifact type
+        - `outputPath`: Where to write the artifact
+        - `dependencies`: Completed artifacts to read for context
+      - Read any completed dependency files for context
+      - Create the artifact file using `template` as the structure
+      - Apply `context` and `rules` as constraints - but do NOT copy them into the file
+      - Show brief progress: "✓ Created <artifact-id>"
+
+   b. **Continue until all `applyRequires` artifacts are complete**
+      - After creating each artifact, re-run `openspec status --change "<name>" --json`
+      - Check if every artifact ID in `applyRequires` has `status: "done"` in the artifacts array
+      - Stop when all `applyRequires` artifacts are done
+
+   c. **If an artifact requires user input** (unclear context):
+      - Use **AskUserQuestion tool** to clarify
+      - Then continue with creation
+
+5. **Show final status**
+   ```bash
+   openspec status --change "<name>"
+   ```
+
+**Output**
+
+After completing all artifacts, summarize:
+- Change name and location
+- List of artifacts created with brief descriptions
+- What's ready: "All artifacts created! Ready for implementation."
+- Prompt: "Run `/opsx:apply` to start implementing."
+
+**Artifact Creation Guidelines**
+
+- Follow the `instruction` field from `openspec instructions` for each artifact type
+- The schema defines what each artifact should contain - follow it
+- Read dependency artifacts for context before creating new ones
+- Use the `template` as a starting point, filling in based on context
+
+**Guardrails**
+- Create ALL artifacts needed for implementation (as defined by schema's `apply.requires`)
+- Always read dependency artifacts before creating a new one
+- If context is critically unclear, ask the user - but prefer making reasonable decisions to keep momentum
+- If a change with that name already exists, ask if user wants to continue it or create a new one
+- Verify each artifact file exists after writing before proceeding to next
diff --git a/.claude/commands/opsx/new.md b/.claude/commands/opsx/new.md
new file mode 100644
index 0000000..ef26cfa
--- /dev/null
+++ b/.claude/commands/opsx/new.md
@@ -0,0 +1,69 @@
+---
+name: "OPSX: New"
+description: Start a new change using the experimental artifact workflow (OPSX)
+category: Workflow
+tags: [workflow, artifacts, experimental]
+---
+
+Start a new change using the experimental artifact-driven approach.
+
+**Input**: The argument after `/opsx:new` is the change name (kebab-case), OR a description of what the user wants to build.
+
+**Steps**
+
+1. **If no input provided, ask what they want to build**
+
+   Use the **AskUserQuestion tool** (open-ended, no preset options) to ask:
+   > "What change do you want to work on? Describe what you want to build or fix."
+
+   From their description, derive a kebab-case name (e.g., "add user authentication" → `add-user-auth`).
+
+   **IMPORTANT**: Do NOT proceed without understanding what the user wants to build.
+
+2. **Determine the workflow schema**
+
+   Use the default schema (omit `--schema`) unless the user explicitly requests a different workflow.
+
+   **Use a different schema only if the user mentions:**
+   - A specific schema name → use `--schema <name>`
+   - "show workflows" or "what workflows" → run `openspec schemas --json` and let them choose
+
+   **Otherwise**: Omit `--schema` to use the default.
+
+3. **Create the change directory**
+   ```bash
+   openspec new change "<name>"
+   ```
+   Add `--schema <name>` only if the user requested a specific workflow.
+   This creates a scaffolded change at `openspec/changes/<name>/` with the selected schema.
+
+4. **Show the artifact status**
+   ```bash
+   openspec status --change "<name>"
+   ```
+   This shows which artifacts need to be created and which are ready (dependencies satisfied).
+
+5. **Get instructions for the first artifact**
+   The first artifact depends on the schema. Check the status output to find the first artifact with status "ready".
+   ```bash
+   openspec instructions <first-artifact-id> --change "<name>"
+   ```
+   This outputs the template and context for creating the first artifact.
+
+6. **STOP and wait for user direction**
+
+**Output**
+
+After completing the steps, summarize:
+- Change name and location
+- Schema/workflow being used and its artifact sequence
+- Current status (0/N artifacts complete)
+- The template for the first artifact
+- Prompt: "Ready to create the first artifact? Run `/opsx:continue` or just describe what this change is about and I'll draft it."
+
+**Guardrails**
+- Do NOT create any artifacts yet - just show the instructions
+- Do NOT advance beyond showing the first artifact template
+- If the name is invalid (not kebab-case), ask for a valid name
+- If a change with that name already exists, suggest using `/opsx:continue` instead
+- Pass --schema if using a non-default workflow
diff --git a/.claude/commands/opsx/sync.md b/.claude/commands/opsx/sync.md
new file mode 100644
index 0000000..1571610
--- /dev/null
+++ b/.claude/commands/opsx/sync.md
@@ -0,0 +1,134 @@
+---
+name: "OPSX: Sync"
+description: Sync delta specs from a change to main specs
+category: Workflow
+tags: [workflow, specs, experimental]
+---
+
+Sync delta specs from a change to main specs.
+
+This is an **agent-driven** operation - you will read delta specs and directly edit main specs to apply the changes. This allows intelligent merging (e.g., adding a scenario without copying the entire requirement).
+
+**Input**: Optionally specify a change name after `/opsx:sync` (e.g., `/opsx:sync add-auth`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **If no change name provided, prompt for selection**
+
+   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+
+   Show changes that have delta specs (under `specs/` directory).
+
+   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
+
+2. **Find delta specs**
+
+   Look for delta spec files in `openspec/changes/<name>/specs/*/spec.md`.
+
+   Each delta spec file contains sections like:
+   - `## ADDED Requirements` - New requirements to add
+   - `## MODIFIED Requirements` - Changes to existing requirements
+   - `## REMOVED Requirements` - Requirements to remove
+   - `## RENAMED Requirements` - Requirements to rename (FROM:/TO: format)
+
+   If no delta specs found, inform user and stop.
+
+3. **For each delta spec, apply changes to main specs**
+
+   For each capability with a delta spec at `openspec/changes/<name>/specs/<capability>/spec.md`:
+
+   a. **Read the delta spec** to understand the intended changes
+
+   b. **Read the main spec** at `openspec/specs/<capability>/spec.md` (may not exist yet)
+
+   c. **Apply changes intelligently**:
+
+      **ADDED Requirements:**
+      - If requirement doesn't exist in main spec → add it
+      - If requirement already exists → update it to match (treat as implicit MODIFIED)
+
+      **MODIFIED Requirements:**
+      - Find the requirement in main spec
+      - Apply the changes - this can be:
+        - Adding new scenarios (don't need to copy existing ones)
+        - Modifying existing scenarios
+        - Changing the requirement description
+      - Preserve scenarios/content not mentioned in the delta
+
+      **REMOVED Requirements:**
+      - Remove the entire requirement block from main spec
+
+      **RENAMED Requirements:**
+      - Find the FROM requirement, rename to TO
+
+   d. **Create new main spec** if capability doesn't exist yet:
+      - Create `openspec/specs/<capability>/spec.md`
+      - Add Purpose section (can be brief, mark as TBD)
+      - Add Requirements section with the ADDED requirements
+
+4. **Show summary**
+
+   After applying all changes, summarize:
+   - Which capabilities were updated
+   - What changes were made (requirements added/modified/removed/renamed)
+
+**Delta Spec Format Reference**
+
+```markdown
+## ADDED Requirements
+
+### Requirement: New Feature
+The system SHALL do something new.
+
+#### Scenario: Basic case
+- **WHEN** user does X
+- **THEN** system does Y
+
+## MODIFIED Requirements
+
+### Requirement: Existing Feature
+#### Scenario: New scenario to add
+- **WHEN** user does A
+- **THEN** system does B
+
+## REMOVED Requirements
+
+### Requirement: Deprecated Feature
+
+## RENAMED Requirements
+
+- FROM: `### Requirement: Old Name`
+- TO: `### Requirement: New Name`
+```
+
+**Key Principle: Intelligent Merging**
+
+Unlike programmatic merging, you can apply **partial updates**:
+- To add a scenario, just include that scenario under MODIFIED - don't copy existing scenarios
+- The delta represents *intent*, not a wholesale replacement
+- Use your judgment to merge changes sensibly
+
+**Output On Success**
+
+```
+## Specs Synced: <change-name>
+
+Updated main specs:
+
+**<capability-1>**:
+- Added requirement: "New Feature"
+- Modified requirement: "Existing Feature" (added 1 scenario)
+
+**<capability-2>**:
+- Created new spec file
+- Added requirement: "Another Feature"
+
+Main specs are now updated. The change remains active - archive when implementation is complete.
+```
+
+**Guardrails**
+- Read both delta and main specs before making changes
+- Preserve existing content not mentioned in delta
+- If something is unclear, ask for clarification
+- Show what you're changing as you go
+- The operation should be idempotent - running twice should give same result
diff --git a/.claude/commands/opsx/verify.md b/.claude/commands/opsx/verify.md
new file mode 100644
index 0000000..82ab63f
--- /dev/null
+++ b/.claude/commands/opsx/verify.md
@@ -0,0 +1,164 @@
+---
+name: "OPSX: Verify"
+description: Verify implementation matches change artifacts before archiving
+category: Workflow
+tags: [workflow, verify, experimental]
+---
+
+Verify that an implementation matches the change artifacts (specs, tasks, design).
+
+**Input**: Optionally specify a change name after `/opsx:verify` (e.g., `/opsx:verify add-auth`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **If no change name provided, prompt for selection**
+
+   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+
+   Show changes that have implementation tasks (tasks artifact exists).
+   Include the schema used for each change if available.
+   Mark changes with incomplete tasks as "(In Progress)".
+
+   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
+
+2. **Check status to understand the schema**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used (e.g., "spec-driven")
+   - Which artifacts exist for this change
+
+3. **Get the change directory and load artifacts**
+
+   ```bash
+   openspec instructions apply --change "<name>" --json
+   ```
+
+   This returns the change directory and context files. Read all available artifacts from `contextFiles`.
+
+4. **Initialize verification report structure**
+
+   Create a report structure with three dimensions:
+   - **Completeness**: Track tasks and spec coverage
+   - **Correctness**: Track requirement implementation and scenario coverage
+   - **Coherence**: Track design adherence and pattern consistency
+
+   Each dimension can have CRITICAL, WARNING, or SUGGESTION issues.
+
+5. **Verify Completeness**
+
+   **Task Completion**:
+   - If tasks.md exists in contextFiles, read it
+   - Parse checkboxes: `- [ ]` (incomplete) vs `- [x]` (complete)
+   - Count complete vs total tasks
+   - If incomplete tasks exist:
+     - Add CRITICAL issue for each incomplete task
+     - Recommendation: "Complete task: <description>" or "Mark as done if already implemented"
+
+   **Spec Coverage**:
+   - If delta specs exist in `openspec/changes/<name>/specs/`:
+     - Extract all requirements (marked with "### Requirement:")
+     - For each requirement:
+       - Search codebase for keywords related to the requirement
+       - Assess if implementation likely exists
+     - If requirements appear unimplemented:
+       - Add CRITICAL issue: "Requirement not found: <requirement name>"
+       - Recommendation: "Implement requirement X: <description>"
+
+6. **Verify Correctness**
+
+   **Requirement Implementation Mapping**:
+   - For each requirement from delta specs:
+     - Search codebase for implementation evidence
+     - If found, note file paths and line ranges
+     - Assess if implementation matches requirement intent
+     - If divergence detected:
+       - Add WARNING: "Implementation may diverge from spec: <details>"
+       - Recommendation: "Review <file>:<lines> against requirement X"
+
+   **Scenario Coverage**:
+   - For each scenario in delta specs (marked with "#### Scenario:"):
+     - Check if conditions are handled in code
+     - Check if tests exist covering the scenario
+     - If scenario appears uncovered:
+       - Add WARNING: "Scenario not covered: <scenario name>"
+       - Recommendation: "Add test or implementation for scenario: <description>"
+
+7. **Verify Coherence**
+
+   **Design Adherence**:
+   - If design.md exists in contextFiles:
+     - Extract key decisions (look for sections like "Decision:", "Approach:", "Architecture:")
+     - Verify implementation follows those decisions
+     - If contradiction detected:
+       - Add WARNING: "Design decision not followed: <decision>"
+       - Recommendation: "Update implementation or revise design.md to match reality"
+   - If no design.md: Skip design adherence check, note "No design.md to verify against"
+
+   **Code Pattern Consistency**:
+   - Review new code for consistency with project patterns
+   - Check file naming, directory structure, coding style
+   - If significant deviations found:
+     - Add SUGGESTION: "Code pattern deviation: <details>"
+     - Recommendation: "Consider following project pattern: <example>"
+
+8. **Generate Verification Report**
+
+   **Summary Scorecard**:
+   ```
+   ## Verification Report: <change-name>
+
+   ### Summary
+   | Dimension    | Status           |
+   |--------------|------------------|
+   | Completeness | X/Y tasks, N reqs|
+   | Correctness  | M/N reqs covered |
+   | Coherence    | Followed/Issues  |
+   ```
+
+   **Issues by Priority**:
+
+   1. **CRITICAL** (Must fix before archive):
+      - Incomplete tasks
+      - Missing requirement implementations
+      - Each with specific, actionable recommendation
+
+   2. **WARNING** (Should fix):
+      - Spec/design divergences
+      - Missing scenario coverage
+      - Each with specific recommendation
+
+   3. **SUGGESTION** (Nice to fix):
+      - Pattern inconsistencies
+      - Minor improvements
+      - Each with specific recommendation
+
+   **Final Assessment**:
+   - If CRITICAL issues: "X critical issue(s) found. Fix before archiving."
+   - If only warnings: "No critical issues. Y warning(s) to consider. Ready for archive (with noted improvements)."
+   - If all clear: "All checks passed. Ready for archive."
+
+**Verification Heuristics**
+
+- **Completeness**: Focus on objective checklist items (checkboxes, requirements list)
+- **Correctness**: Use keyword search, file path analysis, reasonable inference - don't require perfect certainty
+- **Coherence**: Look for glaring inconsistencies, don't nitpick style
+- **False Positives**: When uncertain, prefer SUGGESTION over WARNING, WARNING over CRITICAL
+- **Actionability**: Every issue must have a specific recommendation with file/line references where applicable
+
+**Graceful Degradation**
+
+- If only tasks.md exists: verify task completion only, skip spec/design checks
+- If tasks + specs exist: verify completeness and correctness, skip design
+- If full artifacts: verify all three dimensions
+- Always note which checks were skipped and why
+
+**Output Format**
+
+Use clear markdown with:
+- Table for summary scorecard
+- Grouped lists for issues (CRITICAL/WARNING/SUGGESTION)
+- Code references in format: `file.ts:123`
+- Specific, actionable recommendations
+- No vague suggestions like "consider reviewing"
diff --git a/.claude/skills/openspec-apply-change/SKILL.md b/.claude/skills/openspec-apply-change/SKILL.md
index 716375a..47d4bc2 100644
--- a/.claude/skills/openspec-apply-change/SKILL.md
+++ b/.claude/skills/openspec-apply-change/SKILL.md
@@ -6,7 +6,7 @@ compatibility: Requires openspec CLI.
 metadata:
   author: openspec
   version: "1.0"
-  generatedBy: "1.3.0"
+  generatedBy: "1.1.1"
 ---
 
 Implement tasks from an OpenSpec change.
diff --git a/.claude/skills/openspec-archive-change/SKILL.md b/.claude/skills/openspec-archive-change/SKILL.md
index 74047c6..8fa4b23 100644
--- a/.claude/skills/openspec-archive-change/SKILL.md
+++ b/.claude/skills/openspec-archive-change/SKILL.md
@@ -6,7 +6,7 @@ compatibility: Requires openspec CLI.
 metadata:
   author: openspec
   version: "1.0"
-  generatedBy: "1.3.0"
+  generatedBy: "1.1.1"
 ---
 
 Archive a completed change in the experimental workflow.
@@ -63,7 +63,7 @@ Archive a completed change in the experimental workflow.
    - If changes needed: "Sync now (recommended)", "Archive without syncing"
    - If already synced: "Archive now", "Sync anyway", "Cancel"
 
-   If user chooses sync, use Task tool (subagent_type: "general-purpose", prompt: "Use Skill tool to invoke openspec-sync-specs for change '<name>'. Delta spec analysis: <include the analyzed delta spec summary>"). Proceed to archive regardless of choice.
+   If user chooses sync, execute /opsx:sync logic (use the openspec-sync-specs skill). Proceed to archive regardless of choice.
 
 5. **Perform the archive**
 
diff --git a/.claude/skills/openspec-bulk-archive-change/SKILL.md b/.claude/skills/openspec-bulk-archive-change/SKILL.md
index 26ec647..719b279 100644
--- a/.claude/skills/openspec-bulk-archive-change/SKILL.md
+++ b/.claude/skills/openspec-bulk-archive-change/SKILL.md
@@ -6,7 +6,7 @@ compatibility: Requires openspec CLI.
 metadata:
   author: openspec
   version: "1.0"
-  generatedBy: "1.3.0"
+  generatedBy: "1.1.1"
 ---
 
 Archive multiple completed changes in a single operation.
@@ -84,7 +84,7 @@ This skill allows you to batch-archive changes, handling spec conflicts intellig
    Display a table summarizing all changes:
 
    ```
-   | Change              | Artifacts | Tasks | Specs   | Conflicts | Status |
+   | Change               | Artifacts | Tasks | Specs   | Conflicts | Status |
    |---------------------|-----------|-------|---------|-----------|--------|
    | schema-management   | Done      | 5/5   | 2 delta | None      | Ready  |
    | project-config      | Done      | 3/3   | 1 delta | None      | Ready  |
@@ -229,7 +229,7 @@ Failed K changes:
 ```
 ## No Changes to Archive
 
-No active changes found. Create a new change to get started.
+No active changes found. Use `/opsx:new` to create a new change.
 ```
 
 **Guardrails**
diff --git a/.claude/skills/openspec-continue-change/SKILL.md b/.claude/skills/openspec-continue-change/SKILL.md
index 19be144..5060b2f 100644
--- a/.claude/skills/openspec-continue-change/SKILL.md
+++ b/.claude/skills/openspec-continue-change/SKILL.md
@@ -6,7 +6,7 @@ compatibility: Requires openspec CLI.
 metadata:
   author: openspec
   version: "1.0"
-  generatedBy: "1.3.0"
+  generatedBy: "1.1.1"
 ---
 
 Continue working on a change by creating the next artifact.
diff --git a/.claude/skills/openspec-explore/SKILL.md b/.claude/skills/openspec-explore/SKILL.md
index 7ca3192..8ed4a76 100644
--- a/.claude/skills/openspec-explore/SKILL.md
+++ b/.claude/skills/openspec-explore/SKILL.md
@@ -6,12 +6,12 @@ compatibility: Requires openspec CLI.
 metadata:
   author: openspec
   version: "1.0"
-  generatedBy: "1.3.0"
+  generatedBy: "1.1.1"
 ---
 
 Enter explore mode. Think deeply. Visualize freely. Follow the conversation wherever it goes.
 
-**IMPORTANT: Explore mode is for thinking, not implementing.** You may read files, search code, and investigate the codebase, but you must NEVER write code or implement features. If the user asks you to implement something, remind them to exit explore mode first and create a change proposal. You MAY create OpenSpec artifacts (proposals, designs, specs) if the user asks—that's capturing thinking, not implementing.
+**IMPORTANT: Explore mode is for thinking, not implementing.** You may read files, search code, and investigate the codebase, but you must NEVER write code or implement features. If the user asks you to implement something, remind them to exit explore mode first (e.g., start a change with `/opsx:new` or `/opsx:ff`). You MAY create OpenSpec artifacts (proposals, designs, specs) if the user asks—that's capturing thinking, not implementing.
 
 **This is a stance, not a workflow.** There are no fixed steps, no required sequence, no mandatory outputs. You're a thinking partner helping the user explore.
 
@@ -56,10 +56,10 @@ Depending on what the user brings, you might:
 │     Use ASCII diagrams liberally        │
 ├─────────────────────────────────────────┤
 │                                         │
-│      ┌────────┐         ┌────────┐      │
-│      │ State  │────────▶│ State  │      │
-│      │   A    │         │   B    │      │
-│      └────────┘         └────────┘      │
+│   ┌────────┐         ┌────────┐        │
+│   │ State  │────────▶│ State  │        │
+│   │   A    │         │   B    │        │
+│   └────────┘         └────────┘        │
 │                                         │
 │   System diagrams, state machines,      │
 │   data flows, architecture sketches,    │
@@ -95,7 +95,8 @@ This tells you:
 
 Think freely. When insights crystallize, you might offer:
 
-- "This feels solid enough to start a change. Want me to create a proposal?"
+- "This feels solid enough to start a change. Want me to create one?"
+  → Can transition to `/opsx:new` or `/opsx:ff`
 - Or keep exploring - no pressure to formalize
 
 ### When a change exists
@@ -114,14 +115,14 @@ If the user mentions a change or you detect one is relevant:
 
 3. **Offer to capture when decisions are made**
 
-    | Insight Type               | Where to Capture               |
-    |----------------------------|--------------------------------|
-    | New requirement discovered | `specs/<capability>/spec.md` |
-    | Requirement changed        | `specs/<capability>/spec.md` |
-    | Design decision made       | `design.md`                  |
-    | Scope changed              | `proposal.md`                |
-    | New work identified        | `tasks.md`                   |
-    | Assumption invalidated     | Relevant artifact              |
+   | Insight Type | Where to Capture |
+   |--------------|------------------|
+   | New requirement discovered | `specs/<capability>/spec.md` |
+   | Requirement changed | `specs/<capability>/spec.md` |
+   | Design decision made | `design.md` |
+   | Scope changed | `proposal.md` |
+   | New work identified | `tasks.md` |
+   | Assumption invalidated | Relevant artifact |
 
    Example offers:
    - "That's a design decision. Capture it in design.md?"
@@ -227,7 +228,7 @@ User: A CLI tool that tracks local dev environments
 You: That changes everything.
 
      ┌─────────────────────────────────────────────────┐
-     │          CLI TOOL DATA STORAGE                  │
+     │         CLI TOOL DATA STORAGE                  │
      └─────────────────────────────────────────────────┘
 
      Key constraints:
@@ -251,7 +252,7 @@ You: That changes everything.
 
 There's no required ending. Discovery might:
 
-- **Flow into a proposal**: "Ready to start? I can create a change proposal."
+- **Flow into action**: "Ready to start? /opsx:new or /opsx:ff"
 - **Result in artifact updates**: "Updated design.md with these decisions"
 - **Just provide clarity**: User has what they need, moves on
 - **Continue later**: "We can pick this up anytime"
@@ -268,7 +269,8 @@ When it feels like things are crystallizing, you might summarize:
 **Open questions**: [if any remain]
 
 **Next steps** (if ready):
-- Create a change proposal
+- Create a change: /opsx:new <name>
+- Fast-forward to tasks: /opsx:ff <name>
 - Keep exploring: just keep talking
 ```
 
diff --git a/.claude/skills/openspec-ff-change/SKILL.md b/.claude/skills/openspec-ff-change/SKILL.md
index 7f795fe..d586012 100644
--- a/.claude/skills/openspec-ff-change/SKILL.md
+++ b/.claude/skills/openspec-ff-change/SKILL.md
@@ -6,7 +6,7 @@ compatibility: Requires openspec CLI.
 metadata:
   author: openspec
   version: "1.0"
-  generatedBy: "1.3.0"
+  generatedBy: "1.1.1"
 ---
 
 Fast-forward through artifact creation - generate everything needed to start implementation in one go.
diff --git a/.claude/skills/openspec-new-change/SKILL.md b/.claude/skills/openspec-new-change/SKILL.md
index cdc877e..37ac7ba 100644
--- a/.claude/skills/openspec-new-change/SKILL.md
+++ b/.claude/skills/openspec-new-change/SKILL.md
@@ -6,7 +6,7 @@ compatibility: Requires openspec CLI.
 metadata:
   author: openspec
   version: "1.0"
-  generatedBy: "1.3.0"
+  generatedBy: "1.1.1"
 ---
 
 Start a new change using the experimental artifact-driven approach.
diff --git a/.claude/skills/openspec-sync-specs/SKILL.md b/.claude/skills/openspec-sync-specs/SKILL.md
index 2823275..4c7e3aa 100644
--- a/.claude/skills/openspec-sync-specs/SKILL.md
+++ b/.claude/skills/openspec-sync-specs/SKILL.md
@@ -6,7 +6,7 @@ compatibility: Requires openspec CLI.
 metadata:
   author: openspec
   version: "1.0"
-  generatedBy: "1.3.0"
+  generatedBy: "1.1.1"
 ---
 
 Sync delta specs from a change to main specs.
diff --git a/.claude/skills/openspec-verify-change/SKILL.md b/.claude/skills/openspec-verify-change/SKILL.md
index fc2ba2a..443ac5f 100644
--- a/.claude/skills/openspec-verify-change/SKILL.md
+++ b/.claude/skills/openspec-verify-change/SKILL.md
@@ -6,7 +6,7 @@ compatibility: Requires openspec CLI.
 metadata:
   author: openspec
   version: "1.0"
-  generatedBy: "1.3.0"
+  generatedBy: "1.1.1"
 ---
 
 Verify that an implementation matches the change artifacts (specs, tasks, design).
diff --git a/.codex/skills/openspec-apply-change/SKILL.md b/.codex/skills/openspec-apply-change/SKILL.md
index 716375a..47d4bc2 100644
--- a/.codex/skills/openspec-apply-change/SKILL.md
+++ b/.codex/skills/openspec-apply-change/SKILL.md
@@ -6,7 +6,7 @@ compatibility: Requires openspec CLI.
 metadata:
   author: openspec
   version: "1.0"
-  generatedBy: "1.3.0"
+  generatedBy: "1.1.1"
 ---
 
 Implement tasks from an OpenSpec change.
diff --git a/.codex/skills/openspec-archive-change/SKILL.md b/.codex/skills/openspec-archive-change/SKILL.md
index 74047c6..8fa4b23 100644
--- a/.codex/skills/openspec-archive-change/SKILL.md
+++ b/.codex/skills/openspec-archive-change/SKILL.md
@@ -6,7 +6,7 @@ compatibility: Requires openspec CLI.
 metadata:
   author: openspec
   version: "1.0"
-  generatedBy: "1.3.0"
+  generatedBy: "1.1.1"
 ---
 
 Archive a completed change in the experimental workflow.
@@ -63,7 +63,7 @@ Archive a completed change in the experimental workflow.
    - If changes needed: "Sync now (recommended)", "Archive without syncing"
    - If already synced: "Archive now", "Sync anyway", "Cancel"
 
-   If user chooses sync, use Task tool (subagent_type: "general-purpose", prompt: "Use Skill tool to invoke openspec-sync-specs for change '<name>'. Delta spec analysis: <include the analyzed delta spec summary>"). Proceed to archive regardless of choice.
+   If user chooses sync, execute /opsx:sync logic (use the openspec-sync-specs skill). Proceed to archive regardless of choice.
 
 5. **Perform the archive**
 
diff --git a/.codex/skills/openspec-bulk-archive-change/SKILL.md b/.codex/skills/openspec-bulk-archive-change/SKILL.md
index 26ec647..719b279 100644
--- a/.codex/skills/openspec-bulk-archive-change/SKILL.md
+++ b/.codex/skills/openspec-bulk-archive-change/SKILL.md
@@ -6,7 +6,7 @@ compatibility: Requires openspec CLI.
 metadata:
   author: openspec
   version: "1.0"
-  generatedBy: "1.3.0"
+  generatedBy: "1.1.1"
 ---
 
 Archive multiple completed changes in a single operation.
@@ -84,7 +84,7 @@ This skill allows you to batch-archive changes, handling spec conflicts intellig
    Display a table summarizing all changes:
 
    ```
-   | Change              | Artifacts | Tasks | Specs   | Conflicts | Status |
+   | Change               | Artifacts | Tasks | Specs   | Conflicts | Status |
    |---------------------|-----------|-------|---------|-----------|--------|
    | schema-management   | Done      | 5/5   | 2 delta | None      | Ready  |
    | project-config      | Done      | 3/3   | 1 delta | None      | Ready  |
@@ -229,7 +229,7 @@ Failed K changes:
 ```
 ## No Changes to Archive
 
-No active changes found. Create a new change to get started.
+No active changes found. Use `/opsx:new` to create a new change.
 ```
 
 **Guardrails**
diff --git a/.codex/skills/openspec-continue-change/SKILL.md b/.codex/skills/openspec-continue-change/SKILL.md
index 19be144..5060b2f 100644
--- a/.codex/skills/openspec-continue-change/SKILL.md
+++ b/.codex/skills/openspec-continue-change/SKILL.md
@@ -6,7 +6,7 @@ compatibility: Requires openspec CLI.
 metadata:
   author: openspec
   version: "1.0"
-  generatedBy: "1.3.0"
+  generatedBy: "1.1.1"
 ---
 
 Continue working on a change by creating the next artifact.
diff --git a/.codex/skills/openspec-explore/SKILL.md b/.codex/skills/openspec-explore/SKILL.md
index 7ca3192..8ed4a76 100644
--- a/.codex/skills/openspec-explore/SKILL.md
+++ b/.codex/skills/openspec-explore/SKILL.md
@@ -6,12 +6,12 @@ compatibility: Requires openspec CLI.
 metadata:
   author: openspec
   version: "1.0"
-  generatedBy: "1.3.0"
+  generatedBy: "1.1.1"
 ---
 
 Enter explore mode. Think deeply. Visualize freely. Follow the conversation wherever it goes.
 
-**IMPORTANT: Explore mode is for thinking, not implementing.** You may read files, search code, and investigate the codebase, but you must NEVER write code or implement features. If the user asks you to implement something, remind them to exit explore mode first and create a change proposal. You MAY create OpenSpec artifacts (proposals, designs, specs) if the user asks—that's capturing thinking, not implementing.
+**IMPORTANT: Explore mode is for thinking, not implementing.** You may read files, search code, and investigate the codebase, but you must NEVER write code or implement features. If the user asks you to implement something, remind them to exit explore mode first (e.g., start a change with `/opsx:new` or `/opsx:ff`). You MAY create OpenSpec artifacts (proposals, designs, specs) if the user asks—that's capturing thinking, not implementing.
 
 **This is a stance, not a workflow.** There are no fixed steps, no required sequence, no mandatory outputs. You're a thinking partner helping the user explore.
 
@@ -56,10 +56,10 @@ Depending on what the user brings, you might:
 │     Use ASCII diagrams liberally        │
 ├─────────────────────────────────────────┤
 │                                         │
-│      ┌────────┐         ┌────────┐      │
-│      │ State  │────────▶│ State  │      │
-│      │   A    │         │   B    │      │
-│      └────────┘         └────────┘      │
+│   ┌────────┐         ┌────────┐        │
+│   │ State  │────────▶│ State  │        │
+│   │   A    │         │   B    │        │
+│   └────────┘         └────────┘        │
 │                                         │
 │   System diagrams, state machines,      │
 │   data flows, architecture sketches,    │
@@ -95,7 +95,8 @@ This tells you:
 
 Think freely. When insights crystallize, you might offer:
 
-- "This feels solid enough to start a change. Want me to create a proposal?"
+- "This feels solid enough to start a change. Want me to create one?"
+  → Can transition to `/opsx:new` or `/opsx:ff`
 - Or keep exploring - no pressure to formalize
 
 ### When a change exists
@@ -114,14 +115,14 @@ If the user mentions a change or you detect one is relevant:
 
 3. **Offer to capture when decisions are made**
 
-    | Insight Type               | Where to Capture               |
-    |----------------------------|--------------------------------|
-    | New requirement discovered | `specs/<capability>/spec.md` |
-    | Requirement changed        | `specs/<capability>/spec.md` |
-    | Design decision made       | `design.md`                  |
-    | Scope changed              | `proposal.md`                |
-    | New work identified        | `tasks.md`                   |
-    | Assumption invalidated     | Relevant artifact              |
+   | Insight Type | Where to Capture |
+   |--------------|------------------|
+   | New requirement discovered | `specs/<capability>/spec.md` |
+   | Requirement changed | `specs/<capability>/spec.md` |
+   | Design decision made | `design.md` |
+   | Scope changed | `proposal.md` |
+   | New work identified | `tasks.md` |
+   | Assumption invalidated | Relevant artifact |
 
    Example offers:
    - "That's a design decision. Capture it in design.md?"
@@ -227,7 +228,7 @@ User: A CLI tool that tracks local dev environments
 You: That changes everything.
 
      ┌─────────────────────────────────────────────────┐
-     │          CLI TOOL DATA STORAGE                  │
+     │         CLI TOOL DATA STORAGE                  │
      └─────────────────────────────────────────────────┘
 
      Key constraints:
@@ -251,7 +252,7 @@ You: That changes everything.
 
 There's no required ending. Discovery might:
 
-- **Flow into a proposal**: "Ready to start? I can create a change proposal."
+- **Flow into action**: "Ready to start? /opsx:new or /opsx:ff"
 - **Result in artifact updates**: "Updated design.md with these decisions"
 - **Just provide clarity**: User has what they need, moves on
 - **Continue later**: "We can pick this up anytime"
@@ -268,7 +269,8 @@ When it feels like things are crystallizing, you might summarize:
 **Open questions**: [if any remain]
 
 **Next steps** (if ready):
-- Create a change proposal
+- Create a change: /opsx:new <name>
+- Fast-forward to tasks: /opsx:ff <name>
 - Keep exploring: just keep talking
 ```
 
diff --git a/.codex/skills/openspec-ff-change/SKILL.md b/.codex/skills/openspec-ff-change/SKILL.md
index 7f795fe..d586012 100644
--- a/.codex/skills/openspec-ff-change/SKILL.md
+++ b/.codex/skills/openspec-ff-change/SKILL.md
@@ -6,7 +6,7 @@ compatibility: Requires openspec CLI.
 metadata:
   author: openspec
   version: "1.0"
-  generatedBy: "1.3.0"
+  generatedBy: "1.1.1"
 ---
 
 Fast-forward through artifact creation - generate everything needed to start implementation in one go.
diff --git a/.codex/skills/openspec-new-change/SKILL.md b/.codex/skills/openspec-new-change/SKILL.md
index cdc877e..37ac7ba 100644
--- a/.codex/skills/openspec-new-change/SKILL.md
+++ b/.codex/skills/openspec-new-change/SKILL.md
@@ -6,7 +6,7 @@ compatibility: Requires openspec CLI.
 metadata:
   author: openspec
   version: "1.0"
-  generatedBy: "1.3.0"
+  generatedBy: "1.1.1"
 ---
 
 Start a new change using the experimental artifact-driven approach.
diff --git a/.codex/skills/openspec-sync-specs/SKILL.md b/.codex/skills/openspec-sync-specs/SKILL.md
index 2823275..4c7e3aa 100644
--- a/.codex/skills/openspec-sync-specs/SKILL.md
+++ b/.codex/skills/openspec-sync-specs/SKILL.md
@@ -6,7 +6,7 @@ compatibility: Requires openspec CLI.
 metadata:
   author: openspec
   version: "1.0"
-  generatedBy: "1.3.0"
+  generatedBy: "1.1.1"
 ---
 
 Sync delta specs from a change to main specs.
diff --git a/.codex/skills/openspec-verify-change/SKILL.md b/.codex/skills/openspec-verify-change/SKILL.md
index fc2ba2a..443ac5f 100644
--- a/.codex/skills/openspec-verify-change/SKILL.md
+++ b/.codex/skills/openspec-verify-change/SKILL.md
@@ -6,7 +6,7 @@ compatibility: Requires openspec CLI.
 metadata:
   author: openspec
   version: "1.0"
-  generatedBy: "1.3.0"
+  generatedBy: "1.1.1"
 ---
 
 Verify that an implementation matches the change artifacts (specs, tasks, design).
diff --git a/.cursor/commands/opsx-apply.md b/.cursor/commands/opsx-apply.md
new file mode 100644
index 0000000..a6b077b
--- /dev/null
+++ b/.cursor/commands/opsx-apply.md
@@ -0,0 +1,152 @@
+---
+name: /opsx-apply
+id: opsx-apply
+category: Workflow
+description: Implement tasks from an OpenSpec change (Experimental)
+---
+
+Implement tasks from an OpenSpec change.
+
+**Input**: Optionally specify a change name (e.g., `/opsx:apply add-auth`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **Select the change**
+
+   If a name is provided, use it. Otherwise:
+   - Infer from conversation context if the user mentioned a change
+   - Auto-select if only one active change exists
+   - If ambiguous, run `openspec list --json` to get available changes and use the **AskUserQuestion tool** to let the user select
+
+   Always announce: "Using change: <name>" and how to override (e.g., `/opsx:apply <other>`).
+
+2. **Check status to understand the schema**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used (e.g., "spec-driven")
+   - Which artifact contains the tasks (typically "tasks" for spec-driven, check status for others)
+
+3. **Get apply instructions**
+
+   ```bash
+   openspec instructions apply --change "<name>" --json
+   ```
+
+   This returns:
+   - Context file paths (varies by schema)
+   - Progress (total, complete, remaining)
+   - Task list with status
+   - Dynamic instruction based on current state
+
+   **Handle states:**
+   - If `state: "blocked"` (missing artifacts): show message, suggest using `/opsx:continue`
+   - If `state: "all_done"`: congratulate, suggest archive
+   - Otherwise: proceed to implementation
+
+4. **Read context files**
+
+   Read the files listed in `contextFiles` from the apply instructions output.
+   The files depend on the schema being used:
+   - **spec-driven**: proposal, specs, design, tasks
+   - Other schemas: follow the contextFiles from CLI output
+
+5. **Show current progress**
+
+   Display:
+   - Schema being used
+   - Progress: "N/M tasks complete"
+   - Remaining tasks overview
+   - Dynamic instruction from CLI
+
+6. **Implement tasks (loop until done or blocked)**
+
+   For each pending task:
+   - Show which task is being worked on
+   - Make the code changes required
+   - Keep changes minimal and focused
+   - Mark task complete in the tasks file: `- [ ]` → `- [x]`
+   - Continue to next task
+
+   **Pause if:**
+   - Task is unclear → ask for clarification
+   - Implementation reveals a design issue → suggest updating artifacts
+   - Error or blocker encountered → report and wait for guidance
+   - User interrupts
+
+7. **On completion or pause, show status**
+
+   Display:
+   - Tasks completed this session
+   - Overall progress: "N/M tasks complete"
+   - If all done: suggest archive
+   - If paused: explain why and wait for guidance
+
+**Output During Implementation**
+
+```
+## Implementing: <change-name> (schema: <schema-name>)
+
+Working on task 3/7: <task description>
+[...implementation happening...]
+✓ Task complete
+
+Working on task 4/7: <task description>
+[...implementation happening...]
+✓ Task complete
+```
+
+**Output On Completion**
+
+```
+## Implementation Complete
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Progress:** 7/7 tasks complete ✓
+
+### Completed This Session
+- [x] Task 1
+- [x] Task 2
+...
+
+All tasks complete! You can archive this change with `/opsx:archive`.
+```
+
+**Output On Pause (Issue Encountered)**
+
+```
+## Implementation Paused
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Progress:** 4/7 tasks complete
+
+### Issue Encountered
+<description of the issue>
+
+**Options:**
+1. <option 1>
+2. <option 2>
+3. Other approach
+
+What would you like to do?
+```
+
+**Guardrails**
+- Keep going through tasks until done or blocked
+- Always read context files before starting (from the apply instructions output)
+- If task is ambiguous, pause and ask before implementing
+- If implementation reveals issues, pause and suggest artifact updates
+- Keep code changes minimal and scoped to each task
+- Update task checkbox immediately after completing each task
+- Pause on errors, blockers, or unclear requirements - don't guess
+- Use contextFiles from CLI output, don't assume specific file names
+
+**Fluid Workflow Integration**
+
+This skill supports the "actions on a change" model:
+
+- **Can be invoked anytime**: Before all artifacts are done (if tasks exist), after partial implementation, interleaved with other actions
+- **Allows artifact updates**: If implementation reveals design issues, suggest updating artifacts - not phase-locked, work fluidly
diff --git a/.cursor/commands/opsx-archive.md b/.cursor/commands/opsx-archive.md
new file mode 100644
index 0000000..5e8476c
--- /dev/null
+++ b/.cursor/commands/opsx-archive.md
@@ -0,0 +1,157 @@
+---
+name: /opsx-archive
+id: opsx-archive
+category: Workflow
+description: Archive a completed change in the experimental workflow
+---
+
+Archive a completed change in the experimental workflow.
+
+**Input**: Optionally specify a change name after `/opsx:archive` (e.g., `/opsx:archive add-auth`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **If no change name provided, prompt for selection**
+
+   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+
+   Show only active changes (not already archived).
+   Include the schema used for each change if available.
+
+   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
+
+2. **Check artifact completion status**
+
+   Run `openspec status --change "<name>" --json` to check artifact completion.
+
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used
+   - `artifacts`: List of artifacts with their status (`done` or other)
+
+   **If any artifacts are not `done`:**
+   - Display warning listing incomplete artifacts
+   - Prompt user for confirmation to continue
+   - Proceed if user confirms
+
+3. **Check task completion status**
+
+   Read the tasks file (typically `tasks.md`) to check for incomplete tasks.
+
+   Count tasks marked with `- [ ]` (incomplete) vs `- [x]` (complete).
+
+   **If incomplete tasks found:**
+   - Display warning showing count of incomplete tasks
+   - Prompt user for confirmation to continue
+   - Proceed if user confirms
+
+   **If no tasks file exists:** Proceed without task-related warning.
+
+4. **Assess delta spec sync state**
+
+   Check for delta specs at `openspec/changes/<name>/specs/`. If none exist, proceed without sync prompt.
+
+   **If delta specs exist:**
+   - Compare each delta spec with its corresponding main spec at `openspec/specs/<capability>/spec.md`
+   - Determine what changes would be applied (adds, modifications, removals, renames)
+   - Show a combined summary before prompting
+
+   **Prompt options:**
+   - If changes needed: "Sync now (recommended)", "Archive without syncing"
+   - If already synced: "Archive now", "Sync anyway", "Cancel"
+
+   If user chooses sync, execute `/opsx:sync` logic. Proceed to archive regardless of choice.
+
+5. **Perform the archive**
+
+   Create the archive directory if it doesn't exist:
+   ```bash
+   mkdir -p openspec/changes/archive
+   ```
+
+   Generate target name using current date: `YYYY-MM-DD-<change-name>`
+
+   **Check if target already exists:**
+   - If yes: Fail with error, suggest renaming existing archive or using different date
+   - If no: Move the change directory to archive
+
+   ```bash
+   mv openspec/changes/<name> openspec/changes/archive/YYYY-MM-DD-<name>
+   ```
+
+6. **Display summary**
+
+   Show archive completion summary including:
+   - Change name
+   - Schema that was used
+   - Archive location
+   - Spec sync status (synced / sync skipped / no delta specs)
+   - Note about any warnings (incomplete artifacts/tasks)
+
+**Output On Success**
+
+```
+## Archive Complete
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Specs:** ✓ Synced to main specs
+
+All artifacts complete. All tasks complete.
+```
+
+**Output On Success (No Delta Specs)**
+
+```
+## Archive Complete
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Specs:** No delta specs
+
+All artifacts complete. All tasks complete.
+```
+
+**Output On Success With Warnings**
+
+```
+## Archive Complete (with warnings)
+
+**Change:** <change-name>
+**Schema:** <schema-name>
+**Archived to:** openspec/changes/archive/YYYY-MM-DD-<name>/
+**Specs:** Sync skipped (user chose to skip)
+
+**Warnings:**
+- Archived with 2 incomplete artifacts
+- Archived with 3 incomplete tasks
+- Delta spec sync was skipped (user chose to skip)
+
+Review the archive if this was not intentional.
+```
+
+**Output On Error (Archive Exists)**
+
+```
+## Archive Failed
+
+**Change:** <change-name>
+**Target:** openspec/changes/archive/YYYY-MM-DD-<name>/
+
+Target archive directory already exists.
+
+**Options:**
+1. Rename the existing archive
+2. Delete the existing archive if it's a duplicate
+3. Wait until a different date to archive
+```
+
+**Guardrails**
+- Always prompt for change selection if not provided
+- Use artifact graph (openspec status --json) for completion checking
+- Don't block archive on warnings - just inform and confirm
+- Preserve .openspec.yaml when moving to archive (it moves with the directory)
+- Show clear summary of what happened
+- If sync is requested, use /opsx:sync approach (agent-driven)
+- If delta specs exist, always run the sync assessment and show the combined summary before prompting
diff --git a/.cursor/commands/opsx-bulk-archive.md b/.cursor/commands/opsx-bulk-archive.md
new file mode 100644
index 0000000..2c564aa
--- /dev/null
+++ b/.cursor/commands/opsx-bulk-archive.md
@@ -0,0 +1,242 @@
+---
+name: /opsx-bulk-archive
+id: opsx-bulk-archive
+category: Workflow
+description: Archive multiple completed changes at once
+---
+
+Archive multiple completed changes in a single operation.
+
+This skill allows you to batch-archive changes, handling spec conflicts intelligently by checking the codebase to determine what's actually implemented.
+
+**Input**: None required (prompts for selection)
+
+**Steps**
+
+1. **Get active changes**
+
+   Run `openspec list --json` to get all active changes.
+
+   If no active changes exist, inform user and stop.
+
+2. **Prompt for change selection**
+
+   Use **AskUserQuestion tool** with multi-select to let user choose changes:
+   - Show each change with its schema
+   - Include an option for "All changes"
+   - Allow any number of selections (1+ works, 2+ is the typical use case)
+
+   **IMPORTANT**: Do NOT auto-select. Always let the user choose.
+
+3. **Batch validation - gather status for all selected changes**
+
+   For each selected change, collect:
+
+   a. **Artifact status** - Run `openspec status --change "<name>" --json`
+      - Parse `schemaName` and `artifacts` list
+      - Note which artifacts are `done` vs other states
+
+   b. **Task completion** - Read `openspec/changes/<name>/tasks.md`
+      - Count `- [ ]` (incomplete) vs `- [x]` (complete)
+      - If no tasks file exists, note as "No tasks"
+
+   c. **Delta specs** - Check `openspec/changes/<name>/specs/` directory
+      - List which capability specs exist
+      - For each, extract requirement names (lines matching `### Requirement: <name>`)
+
+4. **Detect spec conflicts**
+
+   Build a map of `capability -> [changes that touch it]`:
+
+   ```
+   auth -> [change-a, change-b]  <- CONFLICT (2+ changes)
+   api  -> [change-c]            <- OK (only 1 change)
+   ```
+
+   A conflict exists when 2+ selected changes have delta specs for the same capability.
+
+5. **Resolve conflicts agentically**
+
+   **For each conflict**, investigate the codebase:
+
+   a. **Read the delta specs** from each conflicting change to understand what each claims to add/modify
+
+   b. **Search the codebase** for implementation evidence:
+      - Look for code implementing requirements from each delta spec
+      - Check for related files, functions, or tests
+
+   c. **Determine resolution**:
+      - If only one change is actually implemented -> sync that one's specs
+      - If both implemented -> apply in chronological order (older first, newer overwrites)
+      - If neither implemented -> skip spec sync, warn user
+
+   d. **Record resolution** for each conflict:
+      - Which change's specs to apply
+      - In what order (if both)
+      - Rationale (what was found in codebase)
+
+6. **Show consolidated status table**
+
+   Display a table summarizing all changes:
+
+   ```
+   | Change               | Artifacts | Tasks | Specs   | Conflicts | Status |
+   |---------------------|-----------|-------|---------|-----------|--------|
+   | schema-management   | Done      | 5/5   | 2 delta | None      | Ready  |
+   | project-config      | Done      | 3/3   | 1 delta | None      | Ready  |
+   | add-oauth           | Done      | 4/4   | 1 delta | auth (!)  | Ready* |
+   | add-verify-skill    | 1 left    | 2/5   | None    | None      | Warn   |
+   ```
+
+   For conflicts, show the resolution:
+   ```
+   * Conflict resolution:
+     - auth spec: Will apply add-oauth then add-jwt (both implemented, chronological order)
+   ```
+
+   For incomplete changes, show warnings:
+   ```
+   Warnings:
+   - add-verify-skill: 1 incomplete artifact, 3 incomplete tasks
+   ```
+
+7. **Confirm batch operation**
+
+   Use **AskUserQuestion tool** with a single confirmation:
+
+   - "Archive N changes?" with options based on status
+   - Options might include:
+     - "Archive all N changes"
+     - "Archive only N ready changes (skip incomplete)"
+     - "Cancel"
+
+   If there are incomplete changes, make clear they'll be archived with warnings.
+
+8. **Execute archive for each confirmed change**
+
+   Process changes in the determined order (respecting conflict resolution):
+
+   a. **Sync specs** if delta specs exist:
+      - Use the openspec-sync-specs approach (agent-driven intelligent merge)
+      - For conflicts, apply in resolved order
+      - Track if sync was done
+
+   b. **Perform the archive**:
+      ```bash
+      mkdir -p openspec/changes/archive
+      mv openspec/changes/<name> openspec/changes/archive/YYYY-MM-DD-<name>
+      ```
+
+   c. **Track outcome** for each change:
+      - Success: archived successfully
+      - Failed: error during archive (record error)
+      - Skipped: user chose not to archive (if applicable)
+
+9. **Display summary**
+
+   Show final results:
+
+   ```
+   ## Bulk Archive Complete
+
+   Archived 3 changes:
+   - schema-management-cli -> archive/2026-01-19-schema-management-cli/
+   - project-config -> archive/2026-01-19-project-config/
+   - add-oauth -> archive/2026-01-19-add-oauth/
+
+   Skipped 1 change:
+   - add-verify-skill (user chose not to archive incomplete)
+
+   Spec sync summary:
+   - 4 delta specs synced to main specs
+   - 1 conflict resolved (auth: applied both in chronological order)
+   ```
+
+   If any failures:
+   ```
+   Failed 1 change:
+   - some-change: Archive directory already exists
+   ```
+
+**Conflict Resolution Examples**
+
+Example 1: Only one implemented
+```
+Conflict: specs/auth/spec.md touched by [add-oauth, add-jwt]
+
+Checking add-oauth:
+- Delta adds "OAuth Provider Integration" requirement
+- Searching codebase... found src/auth/oauth.ts implementing OAuth flow
+
+Checking add-jwt:
+- Delta adds "JWT Token Handling" requirement
+- Searching codebase... no JWT implementation found
+
+Resolution: Only add-oauth is implemented. Will sync add-oauth specs only.
+```
+
+Example 2: Both implemented
+```
+Conflict: specs/api/spec.md touched by [add-rest-api, add-graphql]
+
+Checking add-rest-api (created 2026-01-10):
+- Delta adds "REST Endpoints" requirement
+- Searching codebase... found src/api/rest.ts
+
+Checking add-graphql (created 2026-01-15):
+- Delta adds "GraphQL Schema" requirement
+- Searching codebase... found src/api/graphql.ts
+
+Resolution: Both implemented. Will apply add-rest-api specs first,
+then add-graphql specs (chronological order, newer takes precedence).
+```
+
+**Output On Success**
+
+```
+## Bulk Archive Complete
+
+Archived N changes:
+- <change-1> -> archive/YYYY-MM-DD-<change-1>/
+- <change-2> -> archive/YYYY-MM-DD-<change-2>/
+
+Spec sync summary:
+- N delta specs synced to main specs
+- No conflicts (or: M conflicts resolved)
+```
+
+**Output On Partial Success**
+
+```
+## Bulk Archive Complete (partial)
+
+Archived N changes:
+- <change-1> -> archive/YYYY-MM-DD-<change-1>/
+
+Skipped M changes:
+- <change-2> (user chose not to archive incomplete)
+
+Failed K changes:
+- <change-3>: Archive directory already exists
+```
+
+**Output When No Changes**
+
+```
+## No Changes to Archive
+
+No active changes found. Use `/opsx:new` to create a new change.
+```
+
+**Guardrails**
+- Allow any number of changes (1+ is fine, 2+ is the typical use case)
+- Always prompt for selection, never auto-select
+- Detect spec conflicts early and resolve by checking codebase
+- When both changes are implemented, apply specs in chronological order
+- Skip spec sync only when implementation is missing (warn user)
+- Show clear per-change status before confirming
+- Use single confirmation for entire batch
+- Track and report all outcomes (success/skip/fail)
+- Preserve .openspec.yaml when moving to archive
+- Archive directory target uses current date: YYYY-MM-DD-<name>
+- If archive target exists, fail that change but continue with others
diff --git a/.cursor/commands/opsx-continue.md b/.cursor/commands/opsx-continue.md
new file mode 100644
index 0000000..2103025
--- /dev/null
+++ b/.cursor/commands/opsx-continue.md
@@ -0,0 +1,114 @@
+---
+name: /opsx-continue
+id: opsx-continue
+category: Workflow
+description: Continue working on a change - create the next artifact (Experimental)
+---
+
+Continue working on a change by creating the next artifact.
+
+**Input**: Optionally specify a change name after `/opsx:continue` (e.g., `/opsx:continue add-auth`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **If no change name provided, prompt for selection**
+
+   Run `openspec list --json` to get available changes sorted by most recently modified. Then use the **AskUserQuestion tool** to let the user select which change to work on.
+
+   Present the top 3-4 most recently modified changes as options, showing:
+   - Change name
+   - Schema (from `schema` field if present, otherwise "spec-driven")
+   - Status (e.g., "0/5 tasks", "complete", "no tasks")
+   - How recently it was modified (from `lastModified` field)
+
+   Mark the most recently modified change as "(Recommended)" since it's likely what the user wants to continue.
+
+   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
+
+2. **Check current status**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to understand current state. The response includes:
+   - `schemaName`: The workflow schema being used (e.g., "spec-driven")
+   - `artifacts`: Array of artifacts with their status ("done", "ready", "blocked")
+   - `isComplete`: Boolean indicating if all artifacts are complete
+
+3. **Act based on status**:
+
+   ---
+
+   **If all artifacts are complete (`isComplete: true`)**:
+   - Congratulate the user
+   - Show final status including the schema used
+   - Suggest: "All artifacts created! You can now implement this change with `/opsx:apply` or archive it with `/opsx:archive`."
+   - STOP
+
+   ---
+
+   **If artifacts are ready to create** (status shows artifacts with `status: "ready"`):
+   - Pick the FIRST artifact with `status: "ready"` from the status output
+   - Get its instructions:
+     ```bash
+     openspec instructions <artifact-id> --change "<name>" --json
+     ```
+   - Parse the JSON. The key fields are:
+     - `context`: Project background (constraints for you - do NOT include in output)
+     - `rules`: Artifact-specific rules (constraints for you - do NOT include in output)
+     - `template`: The structure to use for your output file
+     - `instruction`: Schema-specific guidance
+     - `outputPath`: Where to write the artifact
+     - `dependencies`: Completed artifacts to read for context
+   - **Create the artifact file**:
+     - Read any completed dependency files for context
+     - Use `template` as the structure - fill in its sections
+     - Apply `context` and `rules` as constraints when writing - but do NOT copy them into the file
+     - Write to the output path specified in instructions
+   - Show what was created and what's now unlocked
+   - STOP after creating ONE artifact
+
+   ---
+
+   **If no artifacts are ready (all blocked)**:
+   - This shouldn't happen with a valid schema
+   - Show status and suggest checking for issues
+
+4. **After creating an artifact, show progress**
+   ```bash
+   openspec status --change "<name>"
+   ```
+
+**Output**
+
+After each invocation, show:
+- Which artifact was created
+- Schema workflow being used
+- Current progress (N/M complete)
+- What artifacts are now unlocked
+- Prompt: "Run `/opsx:continue` to create the next artifact"
+
+**Artifact Creation Guidelines**
+
+The artifact types and their purpose depend on the schema. Use the `instruction` field from the instructions output to understand what to create.
+
+Common artifact patterns:
+
+**spec-driven schema** (proposal → specs → design → tasks):
+- **proposal.md**: Ask user about the change if not clear. Fill in Why, What Changes, Capabilities, Impact.
+  - The Capabilities section is critical - each capability listed will need a spec file.
+- **specs/<capability>/spec.md**: Create one spec per capability listed in the proposal's Capabilities section (use the capability name, not the change name).
+- **design.md**: Document technical decisions, architecture, and implementation approach.
+- **tasks.md**: Break down implementation into checkboxed tasks.
+
+For other schemas, follow the `instruction` field from the CLI output.
+
+**Guardrails**
+- Create ONE artifact per invocation
+- Always read dependency artifacts before creating a new one
+- Never skip artifacts or create out of order
+- If context is unclear, ask the user before creating
+- Verify the artifact file exists after writing before marking progress
+- Use the schema's artifact sequence, don't assume specific artifact names
+- **IMPORTANT**: `context` and `rules` are constraints for YOU, not content for the file
+  - Do NOT copy `<context>`, `<rules>`, `<project_context>` blocks into the artifact
+  - These guide what you write, but should never appear in the output
diff --git a/.cursor/commands/opsx-explore.md b/.cursor/commands/opsx-explore.md
new file mode 100644
index 0000000..eb8fd88
--- /dev/null
+++ b/.cursor/commands/opsx-explore.md
@@ -0,0 +1,174 @@
+---
+name: /opsx-explore
+id: opsx-explore
+category: Workflow
+description: "Enter explore mode - think through ideas, investigate problems, clarify requirements"
+---
+
+Enter explore mode. Think deeply. Visualize freely. Follow the conversation wherever it goes.
+
+**IMPORTANT: Explore mode is for thinking, not implementing.** You may read files, search code, and investigate the codebase, but you must NEVER write code or implement features. If the user asks you to implement something, remind them to exit explore mode first (e.g., start a change with `/opsx:new` or `/opsx:ff`). You MAY create OpenSpec artifacts (proposals, designs, specs) if the user asks—that's capturing thinking, not implementing.
+
+**This is a stance, not a workflow.** There are no fixed steps, no required sequence, no mandatory outputs. You're a thinking partner helping the user explore.
+
+**Input**: The argument after `/opsx:explore` is whatever the user wants to think about. Could be:
+- A vague idea: "real-time collaboration"
+- A specific problem: "the auth system is getting unwieldy"
+- A change name: "add-dark-mode" (to explore in context of that change)
+- A comparison: "postgres vs sqlite for this"
+- Nothing (just enter explore mode)
+
+---
+
+## The Stance
+
+- **Curious, not prescriptive** - Ask questions that emerge naturally, don't follow a script
+- **Open threads, not interrogations** - Surface multiple interesting directions and let the user follow what resonates. Don't funnel them through a single path of questions.
+- **Visual** - Use ASCII diagrams liberally when they'd help clarify thinking
+- **Adaptive** - Follow interesting threads, pivot when new information emerges
+- **Patient** - Don't rush to conclusions, let the shape of the problem emerge
+- **Grounded** - Explore the actual codebase when relevant, don't just theorize
+
+---
+
+## What You Might Do
+
+Depending on what the user brings, you might:
+
+**Explore the problem space**
+- Ask clarifying questions that emerge from what they said
+- Challenge assumptions
+- Reframe the problem
+- Find analogies
+
+**Investigate the codebase**
+- Map existing architecture relevant to the discussion
+- Find integration points
+- Identify patterns already in use
+- Surface hidden complexity
+
+**Compare options**
+- Brainstorm multiple approaches
+- Build comparison tables
+- Sketch tradeoffs
+- Recommend a path (if asked)
+
+**Visualize**
+```
+┌─────────────────────────────────────────┐
+│     Use ASCII diagrams liberally        │
+├─────────────────────────────────────────┤
+│                                         │
+│   ┌────────┐         ┌────────┐        │
+│   │ State  │────────▶│ State  │        │
+│   │   A    │         │   B    │        │
+│   └────────┘         └────────┘        │
+│                                         │
+│   System diagrams, state machines,      │
+│   data flows, architecture sketches,    │
+│   dependency graphs, comparison tables  │
+│                                         │
+└─────────────────────────────────────────┘
+```
+
+**Surface risks and unknowns**
+- Identify what could go wrong
+- Find gaps in understanding
+- Suggest spikes or investigations
+
+---
+
+## OpenSpec Awareness
+
+You have full context of the OpenSpec system. Use it naturally, don't force it.
+
+### Check for context
+
+At the start, quickly check what exists:
+```bash
+openspec list --json
+```
+
+This tells you:
+- If there are active changes
+- Their names, schemas, and status
+- What the user might be working on
+
+If the user mentioned a specific change name, read its artifacts for context.
+
+### When no change exists
+
+Think freely. When insights crystallize, you might offer:
+
+- "This feels solid enough to start a change. Want me to create one?"
+  → Can transition to `/opsx:new` or `/opsx:ff`
+- Or keep exploring - no pressure to formalize
+
+### When a change exists
+
+If the user mentions a change or you detect one is relevant:
+
+1. **Read existing artifacts for context**
+   - `openspec/changes/<name>/proposal.md`
+   - `openspec/changes/<name>/design.md`
+   - `openspec/changes/<name>/tasks.md`
+   - etc.
+
+2. **Reference them naturally in conversation**
+   - "Your design mentions using Redis, but we just realized SQLite fits better..."
+   - "The proposal scopes this to premium users, but we're now thinking everyone..."
+
+3. **Offer to capture when decisions are made**
+
+   | Insight Type | Where to Capture |
+   |--------------|------------------|
+   | New requirement discovered | `specs/<capability>/spec.md` |
+   | Requirement changed | `specs/<capability>/spec.md` |
+   | Design decision made | `design.md` |
+   | Scope changed | `proposal.md` |
+   | New work identified | `tasks.md` |
+   | Assumption invalidated | Relevant artifact |
+
+   Example offers:
+   - "That's a design decision. Capture it in design.md?"
+   - "This is a new requirement. Add it to specs?"
+   - "This changes scope. Update the proposal?"
+
+4. **The user decides** - Offer and move on. Don't pressure. Don't auto-capture.
+
+---
+
+## What You Don't Have To Do
+
+- Follow a script
+- Ask the same questions every time
+- Produce a specific artifact
+- Reach a conclusion
+- Stay on topic if a tangent is valuable
+- Be brief (this is thinking time)
+
+---
+
+## Ending Discovery
+
+There's no required ending. Discovery might:
+
+- **Flow into action**: "Ready to start? `/opsx:new` or `/opsx:ff`"
+- **Result in artifact updates**: "Updated design.md with these decisions"
+- **Just provide clarity**: User has what they need, moves on
+- **Continue later**: "We can pick this up anytime"
+
+When things crystallize, you might offer a summary - but it's optional. Sometimes the thinking IS the value.
+
+---
+
+## Guardrails
+
+- **Don't implement** - Never write code or implement features. Creating OpenSpec artifacts is fine, writing application code is not.
+- **Don't fake understanding** - If something is unclear, dig deeper
+- **Don't rush** - Discovery is thinking time, not task time
+- **Don't force structure** - Let patterns emerge naturally
+- **Don't auto-capture** - Offer to save insights, don't just do it
+- **Do visualize** - A good diagram is worth many paragraphs
+- **Do explore the codebase** - Ground discussions in reality
+- **Do question assumptions** - Including the user's and your own
diff --git a/.cursor/commands/opsx-ff.md b/.cursor/commands/opsx-ff.md
new file mode 100644
index 0000000..c721915
--- /dev/null
+++ b/.cursor/commands/opsx-ff.md
@@ -0,0 +1,94 @@
+---
+name: /opsx-ff
+id: opsx-ff
+category: Workflow
+description: Create a change and generate all artifacts needed for implementation in one go
+---
+
+Fast-forward through artifact creation - generate everything needed to start implementation.
+
+**Input**: The argument after `/opsx:ff` is the change name (kebab-case), OR a description of what the user wants to build.
+
+**Steps**
+
+1. **If no input provided, ask what they want to build**
+
+   Use the **AskUserQuestion tool** (open-ended, no preset options) to ask:
+   > "What change do you want to work on? Describe what you want to build or fix."
+
+   From their description, derive a kebab-case name (e.g., "add user authentication" → `add-user-auth`).
+
+   **IMPORTANT**: Do NOT proceed without understanding what the user wants to build.
+
+2. **Create the change directory**
+   ```bash
+   openspec new change "<name>"
+   ```
+   This creates a scaffolded change at `openspec/changes/<name>/`.
+
+3. **Get the artifact build order**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to get:
+   - `applyRequires`: array of artifact IDs needed before implementation (e.g., `["tasks"]`)
+   - `artifacts`: list of all artifacts with their status and dependencies
+
+4. **Create artifacts in sequence until apply-ready**
+
+   Use the **TodoWrite tool** to track progress through the artifacts.
+
+   Loop through artifacts in dependency order (artifacts with no pending dependencies first):
+
+   a. **For each artifact that is `ready` (dependencies satisfied)**:
+      - Get instructions:
+        ```bash
+        openspec instructions <artifact-id> --change "<name>" --json
+        ```
+      - The instructions JSON includes:
+        - `context`: Project background (constraints for you - do NOT include in output)
+        - `rules`: Artifact-specific rules (constraints for you - do NOT include in output)
+        - `template`: The structure to use for your output file
+        - `instruction`: Schema-specific guidance for this artifact type
+        - `outputPath`: Where to write the artifact
+        - `dependencies`: Completed artifacts to read for context
+      - Read any completed dependency files for context
+      - Create the artifact file using `template` as the structure
+      - Apply `context` and `rules` as constraints - but do NOT copy them into the file
+      - Show brief progress: "✓ Created <artifact-id>"
+
+   b. **Continue until all `applyRequires` artifacts are complete**
+      - After creating each artifact, re-run `openspec status --change "<name>" --json`
+      - Check if every artifact ID in `applyRequires` has `status: "done"` in the artifacts array
+      - Stop when all `applyRequires` artifacts are done
+
+   c. **If an artifact requires user input** (unclear context):
+      - Use **AskUserQuestion tool** to clarify
+      - Then continue with creation
+
+5. **Show final status**
+   ```bash
+   openspec status --change "<name>"
+   ```
+
+**Output**
+
+After completing all artifacts, summarize:
+- Change name and location
+- List of artifacts created with brief descriptions
+- What's ready: "All artifacts created! Ready for implementation."
+- Prompt: "Run `/opsx:apply` to start implementing."
+
+**Artifact Creation Guidelines**
+
+- Follow the `instruction` field from `openspec instructions` for each artifact type
+- The schema defines what each artifact should contain - follow it
+- Read dependency artifacts for context before creating new ones
+- Use the `template` as a starting point, filling in based on context
+
+**Guardrails**
+- Create ALL artifacts needed for implementation (as defined by schema's `apply.requires`)
+- Always read dependency artifacts before creating a new one
+- If context is critically unclear, ask the user - but prefer making reasonable decisions to keep momentum
+- If a change with that name already exists, ask if user wants to continue it or create a new one
+- Verify each artifact file exists after writing before proceeding to next
diff --git a/.cursor/commands/opsx-new.md b/.cursor/commands/opsx-new.md
new file mode 100644
index 0000000..9f6c795
--- /dev/null
+++ b/.cursor/commands/opsx-new.md
@@ -0,0 +1,69 @@
+---
+name: /opsx-new
+id: opsx-new
+category: Workflow
+description: Start a new change using the experimental artifact workflow (OPSX)
+---
+
+Start a new change using the experimental artifact-driven approach.
+
+**Input**: The argument after `/opsx:new` is the change name (kebab-case), OR a description of what the user wants to build.
+
+**Steps**
+
+1. **If no input provided, ask what they want to build**
+
+   Use the **AskUserQuestion tool** (open-ended, no preset options) to ask:
+   > "What change do you want to work on? Describe what you want to build or fix."
+
+   From their description, derive a kebab-case name (e.g., "add user authentication" → `add-user-auth`).
+
+   **IMPORTANT**: Do NOT proceed without understanding what the user wants to build.
+
+2. **Determine the workflow schema**
+
+   Use the default schema (omit `--schema`) unless the user explicitly requests a different workflow.
+
+   **Use a different schema only if the user mentions:**
+   - A specific schema name → use `--schema <name>`
+   - "show workflows" or "what workflows" → run `openspec schemas --json` and let them choose
+
+   **Otherwise**: Omit `--schema` to use the default.
+
+3. **Create the change directory**
+   ```bash
+   openspec new change "<name>"
+   ```
+   Add `--schema <name>` only if the user requested a specific workflow.
+   This creates a scaffolded change at `openspec/changes/<name>/` with the selected schema.
+
+4. **Show the artifact status**
+   ```bash
+   openspec status --change "<name>"
+   ```
+   This shows which artifacts need to be created and which are ready (dependencies satisfied).
+
+5. **Get instructions for the first artifact**
+   The first artifact depends on the schema. Check the status output to find the first artifact with status "ready".
+   ```bash
+   openspec instructions <first-artifact-id> --change "<name>"
+   ```
+   This outputs the template and context for creating the first artifact.
+
+6. **STOP and wait for user direction**
+
+**Output**
+
+After completing the steps, summarize:
+- Change name and location
+- Schema/workflow being used and its artifact sequence
+- Current status (0/N artifacts complete)
+- The template for the first artifact
+- Prompt: "Ready to create the first artifact? Run `/opsx:continue` or just describe what this change is about and I'll draft it."
+
+**Guardrails**
+- Do NOT create any artifacts yet - just show the instructions
+- Do NOT advance beyond showing the first artifact template
+- If the name is invalid (not kebab-case), ask for a valid name
+- If a change with that name already exists, suggest using `/opsx:continue` instead
+- Pass --schema if using a non-default workflow
diff --git a/.cursor/commands/opsx-sync.md b/.cursor/commands/opsx-sync.md
new file mode 100644
index 0000000..b5f4036
--- /dev/null
+++ b/.cursor/commands/opsx-sync.md
@@ -0,0 +1,134 @@
+---
+name: /opsx-sync
+id: opsx-sync
+category: Workflow
+description: Sync delta specs from a change to main specs
+---
+
+Sync delta specs from a change to main specs.
+
+This is an **agent-driven** operation - you will read delta specs and directly edit main specs to apply the changes. This allows intelligent merging (e.g., adding a scenario without copying the entire requirement).
+
+**Input**: Optionally specify a change name after `/opsx:sync` (e.g., `/opsx:sync add-auth`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **If no change name provided, prompt for selection**
+
+   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+
+   Show changes that have delta specs (under `specs/` directory).
+
+   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
+
+2. **Find delta specs**
+
+   Look for delta spec files in `openspec/changes/<name>/specs/*/spec.md`.
+
+   Each delta spec file contains sections like:
+   - `## ADDED Requirements` - New requirements to add
+   - `## MODIFIED Requirements` - Changes to existing requirements
+   - `## REMOVED Requirements` - Requirements to remove
+   - `## RENAMED Requirements` - Requirements to rename (FROM:/TO: format)
+
+   If no delta specs found, inform user and stop.
+
+3. **For each delta spec, apply changes to main specs**
+
+   For each capability with a delta spec at `openspec/changes/<name>/specs/<capability>/spec.md`:
+
+   a. **Read the delta spec** to understand the intended changes
+
+   b. **Read the main spec** at `openspec/specs/<capability>/spec.md` (may not exist yet)
+
+   c. **Apply changes intelligently**:
+
+      **ADDED Requirements:**
+      - If requirement doesn't exist in main spec → add it
+      - If requirement already exists → update it to match (treat as implicit MODIFIED)
+
+      **MODIFIED Requirements:**
+      - Find the requirement in main spec
+      - Apply the changes - this can be:
+        - Adding new scenarios (don't need to copy existing ones)
+        - Modifying existing scenarios
+        - Changing the requirement description
+      - Preserve scenarios/content not mentioned in the delta
+
+      **REMOVED Requirements:**
+      - Remove the entire requirement block from main spec
+
+      **RENAMED Requirements:**
+      - Find the FROM requirement, rename to TO
+
+   d. **Create new main spec** if capability doesn't exist yet:
+      - Create `openspec/specs/<capability>/spec.md`
+      - Add Purpose section (can be brief, mark as TBD)
+      - Add Requirements section with the ADDED requirements
+
+4. **Show summary**
+
+   After applying all changes, summarize:
+   - Which capabilities were updated
+   - What changes were made (requirements added/modified/removed/renamed)
+
+**Delta Spec Format Reference**
+
+```markdown
+## ADDED Requirements
+
+### Requirement: New Feature
+The system SHALL do something new.
+
+#### Scenario: Basic case
+- **WHEN** user does X
+- **THEN** system does Y
+
+## MODIFIED Requirements
+
+### Requirement: Existing Feature
+#### Scenario: New scenario to add
+- **WHEN** user does A
+- **THEN** system does B
+
+## REMOVED Requirements
+
+### Requirement: Deprecated Feature
+
+## RENAMED Requirements
+
+- FROM: `### Requirement: Old Name`
+- TO: `### Requirement: New Name`
+```
+
+**Key Principle: Intelligent Merging**
+
+Unlike programmatic merging, you can apply **partial updates**:
+- To add a scenario, just include that scenario under MODIFIED - don't copy existing scenarios
+- The delta represents *intent*, not a wholesale replacement
+- Use your judgment to merge changes sensibly
+
+**Output On Success**
+
+```
+## Specs Synced: <change-name>
+
+Updated main specs:
+
+**<capability-1>**:
+- Added requirement: "New Feature"
+- Modified requirement: "Existing Feature" (added 1 scenario)
+
+**<capability-2>**:
+- Created new spec file
+- Added requirement: "Another Feature"
+
+Main specs are now updated. The change remains active - archive when implementation is complete.
+```
+
+**Guardrails**
+- Read both delta and main specs before making changes
+- Preserve existing content not mentioned in delta
+- If something is unclear, ask for clarification
+- Show what you're changing as you go
+- The operation should be idempotent - running twice should give same result
diff --git a/.cursor/commands/opsx-verify.md b/.cursor/commands/opsx-verify.md
new file mode 100644
index 0000000..b87c212
--- /dev/null
+++ b/.cursor/commands/opsx-verify.md
@@ -0,0 +1,164 @@
+---
+name: /opsx-verify
+id: opsx-verify
+category: Workflow
+description: Verify implementation matches change artifacts before archiving
+---
+
+Verify that an implementation matches the change artifacts (specs, tasks, design).
+
+**Input**: Optionally specify a change name after `/opsx:verify` (e.g., `/opsx:verify add-auth`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **If no change name provided, prompt for selection**
+
+   Run `openspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
+
+   Show changes that have implementation tasks (tasks artifact exists).
+   Include the schema used for each change if available.
+   Mark changes with incomplete tasks as "(In Progress)".
+
+   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
+
+2. **Check status to understand the schema**
+   ```bash
+   openspec status --change "<name>" --json
+   ```
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used (e.g., "spec-driven")
+   - Which artifacts exist for this change
+
+3. **Get the change directory and load artifacts**
+
+   ```bash
+   openspec instructions apply --change "<name>" --json
+   ```
+
+   This returns the change directory and context files. Read all available artifacts from `contextFiles`.
+
+4. **Initialize verification report structure**
+
+   Create a report structure with three dimensions:
+   - **Completeness**: Track tasks and spec coverage
+   - **Correctness**: Track requirement implementation and scenario coverage
+   - **Coherence**: Track design adherence and pattern consistency
+
+   Each dimension can have CRITICAL, WARNING, or SUGGESTION issues.
+
+5. **Verify Completeness**
+
+   **Task Completion**:
+   - If tasks.md exists in contextFiles, read it
+   - Parse checkboxes: `- [ ]` (incomplete) vs `- [x]` (complete)
+   - Count complete vs total tasks
+   - If incomplete tasks exist:
+     - Add CRITICAL issue for each incomplete task
+     - Recommendation: "Complete task: <description>" or "Mark as done if already implemented"
+
+   **Spec Coverage**:
+   - If delta specs exist in `openspec/changes/<name>/specs/`:
+     - Extract all requirements (marked with "### Requirement:")
+     - For each requirement:
+       - Search codebase for keywords related to the requirement
+       - Assess if implementation likely exists
+     - If requirements appear unimplemented:
+       - Add CRITICAL issue: "Requirement not found: <requirement name>"
+       - Recommendation: "Implement requirement X: <description>"
+
+6. **Verify Correctness**
+
+   **Requirement Implementation Mapping**:
+   - For each requirement from delta specs:
+     - Search codebase for implementation evidence
+     - If found, note file paths and line ranges
+     - Assess if implementation matches requirement intent
+     - If divergence detected:
+       - Add WARNING: "Implementation may diverge from spec: <details>"
+       - Recommendation: "Review <file>:<lines> against requirement X"
+
+   **Scenario Coverage**:
+   - For each scenario in delta specs (marked with "#### Scenario:"):
+     - Check if conditions are handled in code
+     - Check if tests exist covering the scenario
+     - If scenario appears uncovered:
+       - Add WARNING: "Scenario not covered: <scenario name>"
+       - Recommendation: "Add test or implementation for scenario: <description>"
+
+7. **Verify Coherence**
+
+   **Design Adherence**:
+   - If design.md exists in contextFiles:
+     - Extract key decisions (look for sections like "Decision:", "Approach:", "Architecture:")
+     - Verify implementation follows those decisions
+     - If contradiction detected:
+       - Add WARNING: "Design decision not followed: <decision>"
+       - Recommendation: "Update implementation or revise design.md to match reality"
+   - If no design.md: Skip design adherence check, note "No design.md to verify against"
+
+   **Code Pattern Consistency**:
+   - Review new code for consistency with project patterns
+   - Check file naming, directory structure, coding style
+   - If significant deviations found:
+     - Add SUGGESTION: "Code pattern deviation: <details>"
+     - Recommendation: "Consider following project pattern: <example>"
+
+8. **Generate Verification Report**
+
+   **Summary Scorecard**:
+   ```
+   ## Verification Report: <change-name>
+
+   ### Summary
+   | Dimension    | Status           |
+   |--------------|------------------|
+   | Completeness | X/Y tasks, N reqs|
+   | Correctness  | M/N reqs covered |
+   | Coherence    | Followed/Issues  |
+   ```
+
+   **Issues by Priority**:
+
+   1. **CRITICAL** (Must fix before archive):
+      - Incomplete tasks
+      - Missing requirement implementations
+      - Each with specific, actionable recommendation
+
+   2. **WARNING** (Should fix):
+      - Spec/design divergences
+      - Missing scenario coverage
+      - Each with specific recommendation
+
+   3. **SUGGESTION** (Nice to fix):
+      - Pattern inconsistencies
+      - Minor improvements
+      - Each with specific recommendation
+
+   **Final Assessment**:
+   - If CRITICAL issues: "X critical issue(s) found. Fix before archiving."
+   - If only warnings: "No critical issues. Y warning(s) to consider. Ready for archive (with noted improvements)."
+   - If all clear: "All checks passed. Ready for archive."
+
+**Verification Heuristics**
+
+- **Completeness**: Focus on objective checklist items (checkboxes, requirements list)
+- **Correctness**: Use keyword search, file path analysis, reasonable inference - don't require perfect certainty
+- **Coherence**: Look for glaring inconsistencies, don't nitpick style
+- **False Positives**: When uncertain, prefer SUGGESTION over WARNING, WARNING over CRITICAL
+- **Actionability**: Every issue must have a specific recommendation with file/line references where applicable
+
+**Graceful Degradation**
+
+- If only tasks.md exists: verify task completion only, skip spec/design checks
+- If tasks + specs exist: verify completeness and correctness, skip design
+- If full artifacts: verify all three dimensions
+- Always note which checks were skipped and why
+
+**Output Format**
+
+Use clear markdown with:
+- Table for summary scorecard
+- Grouped lists for issues (CRITICAL/WARNING/SUGGESTION)
+- Code references in format: `file.ts:123`
+- Specific, actionable recommendations
+- No vague suggestions like "consider reviewing"
diff --git a/.cursor/skills/openspec-apply-change/SKILL.md b/.cursor/skills/openspec-apply-change/SKILL.md
index 716375a..47d4bc2 100644
--- a/.cursor/skills/openspec-apply-change/SKILL.md
+++ b/.cursor/skills/openspec-apply-change/SKILL.md
@@ -6,7 +6,7 @@ compatibility: Requires openspec CLI.
 metadata:
   author: openspec
   version: "1.0"
-  generatedBy: "1.3.0"
+  generatedBy: "1.1.1"
 ---
 
 Implement tasks from an OpenSpec change.
diff --git a/.cursor/skills/openspec-archive-change/SKILL.md b/.cursor/skills/openspec-archive-change/SKILL.md
index 74047c6..8fa4b23 100644
--- a/.cursor/skills/openspec-archive-change/SKILL.md
+++ b/.cursor/skills/openspec-archive-change/SKILL.md
@@ -6,7 +6,7 @@ compatibility: Requires openspec CLI.
 metadata:
   author: openspec
   version: "1.0"
-  generatedBy: "1.3.0"
+  generatedBy: "1.1.1"
 ---
 
 Archive a completed change in the experimental workflow.
@@ -63,7 +63,7 @@ Archive a completed change in the experimental workflow.
    - If changes needed: "Sync now (recommended)", "Archive without syncing"
    - If already synced: "Archive now", "Sync anyway", "Cancel"
 
-   If user chooses sync, use Task tool (subagent_type: "general-purpose", prompt: "Use Skill tool to invoke openspec-sync-specs for change '<name>'. Delta spec analysis: <include the analyzed delta spec summary>"). Proceed to archive regardless of choice.
+   If user chooses sync, execute /opsx:sync logic (use the openspec-sync-specs skill). Proceed to archive regardless of choice.
 
 5. **Perform the archive**
 
diff --git a/.cursor/skills/openspec-bulk-archive-change/SKILL.md b/.cursor/skills/openspec-bulk-archive-change/SKILL.md
index 26ec647..719b279 100644
--- a/.cursor/skills/openspec-bulk-archive-change/SKILL.md
+++ b/.cursor/skills/openspec-bulk-archive-change/SKILL.md
@@ -6,7 +6,7 @@ compatibility: Requires openspec CLI.
 metadata:
   author: openspec
   version: "1.0"
-  generatedBy: "1.3.0"
+  generatedBy: "1.1.1"
 ---
 
 Archive multiple completed changes in a single operation.
@@ -84,7 +84,7 @@ This skill allows you to batch-archive changes, handling spec conflicts intellig
    Display a table summarizing all changes:
 
    ```
-   | Change              | Artifacts | Tasks | Specs   | Conflicts | Status |
+   | Change               | Artifacts | Tasks | Specs   | Conflicts | Status |
    |---------------------|-----------|-------|---------|-----------|--------|
    | schema-management   | Done      | 5/5   | 2 delta | None      | Ready  |
    | project-config      | Done      | 3/3   | 1 delta | None      | Ready  |
@@ -229,7 +229,7 @@ Failed K changes:
 ```
 ## No Changes to Archive
 
-No active changes found. Create a new change to get started.
+No active changes found. Use `/opsx:new` to create a new change.
 ```
 
 **Guardrails**
diff --git a/.cursor/skills/openspec-continue-change/SKILL.md b/.cursor/skills/openspec-continue-change/SKILL.md
index 19be144..5060b2f 100644
--- a/.cursor/skills/openspec-continue-change/SKILL.md
+++ b/.cursor/skills/openspec-continue-change/SKILL.md
@@ -6,7 +6,7 @@ compatibility: Requires openspec CLI.
 metadata:
   author: openspec
   version: "1.0"
-  generatedBy: "1.3.0"
+  generatedBy: "1.1.1"
 ---
 
 Continue working on a change by creating the next artifact.
diff --git a/.cursor/skills/openspec-explore/SKILL.md b/.cursor/skills/openspec-explore/SKILL.md
index 7ca3192..8ed4a76 100644
--- a/.cursor/skills/openspec-explore/SKILL.md
+++ b/.cursor/skills/openspec-explore/SKILL.md
@@ -6,12 +6,12 @@ compatibility: Requires openspec CLI.
 metadata:
   author: openspec
   version: "1.0"
-  generatedBy: "1.3.0"
+  generatedBy: "1.1.1"
 ---
 
 Enter explore mode. Think deeply. Visualize freely. Follow the conversation wherever it goes.
 
-**IMPORTANT: Explore mode is for thinking, not implementing.** You may read files, search code, and investigate the codebase, but you must NEVER write code or implement features. If the user asks you to implement something, remind them to exit explore mode first and create a change proposal. You MAY create OpenSpec artifacts (proposals, designs, specs) if the user asks—that's capturing thinking, not implementing.
+**IMPORTANT: Explore mode is for thinking, not implementing.** You may read files, search code, and investigate the codebase, but you must NEVER write code or implement features. If the user asks you to implement something, remind them to exit explore mode first (e.g., start a change with `/opsx:new` or `/opsx:ff`). You MAY create OpenSpec artifacts (proposals, designs, specs) if the user asks—that's capturing thinking, not implementing.
 
 **This is a stance, not a workflow.** There are no fixed steps, no required sequence, no mandatory outputs. You're a thinking partner helping the user explore.
 
@@ -56,10 +56,10 @@ Depending on what the user brings, you might:
 │     Use ASCII diagrams liberally        │
 ├─────────────────────────────────────────┤
 │                                         │
-│      ┌────────┐         ┌────────┐      │
-│      │ State  │────────▶│ State  │      │
-│      │   A    │         │   B    │      │
-│      └────────┘         └────────┘      │
+│   ┌────────┐         ┌────────┐        │
+│   │ State  │────────▶│ State  │        │
+│   │   A    │         │   B    │        │
+│   └────────┘         └────────┘        │
 │                                         │
 │   System diagrams, state machines,      │
 │   data flows, architecture sketches,    │
@@ -95,7 +95,8 @@ This tells you:
 
 Think freely. When insights crystallize, you might offer:
 
-- "This feels solid enough to start a change. Want me to create a proposal?"
+- "This feels solid enough to start a change. Want me to create one?"
+  → Can transition to `/opsx:new` or `/opsx:ff`
 - Or keep exploring - no pressure to formalize
 
 ### When a change exists
@@ -114,14 +115,14 @@ If the user mentions a change or you detect one is relevant:
 
 3. **Offer to capture when decisions are made**
 
-    | Insight Type               | Where to Capture               |
-    |----------------------------|--------------------------------|
-    | New requirement discovered | `specs/<capability>/spec.md` |
-    | Requirement changed        | `specs/<capability>/spec.md` |
-    | Design decision made       | `design.md`                  |
-    | Scope changed              | `proposal.md`                |
-    | New work identified        | `tasks.md`                   |
-    | Assumption invalidated     | Relevant artifact              |
+   | Insight Type | Where to Capture |
+   |--------------|------------------|
+   | New requirement discovered | `specs/<capability>/spec.md` |
+   | Requirement changed | `specs/<capability>/spec.md` |
+   | Design decision made | `design.md` |
+   | Scope changed | `proposal.md` |
+   | New work identified | `tasks.md` |
+   | Assumption invalidated | Relevant artifact |
 
    Example offers:
    - "That's a design decision. Capture it in design.md?"
@@ -227,7 +228,7 @@ User: A CLI tool that tracks local dev environments
 You: That changes everything.
 
      ┌─────────────────────────────────────────────────┐
-     │          CLI TOOL DATA STORAGE                  │
+     │         CLI TOOL DATA STORAGE                  │
      └─────────────────────────────────────────────────┘
 
      Key constraints:
@@ -251,7 +252,7 @@ You: That changes everything.
 
 There's no required ending. Discovery might:
 
-- **Flow into a proposal**: "Ready to start? I can create a change proposal."
+- **Flow into action**: "Ready to start? /opsx:new or /opsx:ff"
 - **Result in artifact updates**: "Updated design.md with these decisions"
 - **Just provide clarity**: User has what they need, moves on
 - **Continue later**: "We can pick this up anytime"
@@ -268,7 +269,8 @@ When it feels like things are crystallizing, you might summarize:
 **Open questions**: [if any remain]
 
 **Next steps** (if ready):
-- Create a change proposal
+- Create a change: /opsx:new <name>
+- Fast-forward to tasks: /opsx:ff <name>
 - Keep exploring: just keep talking
 ```
 
diff --git a/.cursor/skills/openspec-ff-change/SKILL.md b/.cursor/skills/openspec-ff-change/SKILL.md
index 7f795fe..d586012 100644
--- a/.cursor/skills/openspec-ff-change/SKILL.md
+++ b/.cursor/skills/openspec-ff-change/SKILL.md
@@ -6,7 +6,7 @@ compatibility: Requires openspec CLI.
 metadata:
   author: openspec
   version: "1.0"
-  generatedBy: "1.3.0"
+  generatedBy: "1.1.1"
 ---
 
 Fast-forward through artifact creation - generate everything needed to start implementation in one go.
diff --git a/.cursor/skills/openspec-new-change/SKILL.md b/.cursor/skills/openspec-new-change/SKILL.md
index cdc877e..37ac7ba 100644
--- a/.cursor/skills/openspec-new-change/SKILL.md
+++ b/.cursor/skills/openspec-new-change/SKILL.md
@@ -6,7 +6,7 @@ compatibility: Requires openspec CLI.
 metadata:
   author: openspec
   version: "1.0"
-  generatedBy: "1.3.0"
+  generatedBy: "1.1.1"
 ---
 
 Start a new change using the experimental artifact-driven approach.
diff --git a/.cursor/skills/openspec-sync-specs/SKILL.md b/.cursor/skills/openspec-sync-specs/SKILL.md
index 2823275..4c7e3aa 100644
--- a/.cursor/skills/openspec-sync-specs/SKILL.md
+++ b/.cursor/skills/openspec-sync-specs/SKILL.md
@@ -6,7 +6,7 @@ compatibility: Requires openspec CLI.
 metadata:
   author: openspec
   version: "1.0"
-  generatedBy: "1.3.0"
+  generatedBy: "1.1.1"
 ---
 
 Sync delta specs from a change to main specs.
diff --git a/.cursor/skills/openspec-verify-change/SKILL.md b/.cursor/skills/openspec-verify-change/SKILL.md
index fc2ba2a..443ac5f 100644
--- a/.cursor/skills/openspec-verify-change/SKILL.md
+++ b/.cursor/skills/openspec-verify-change/SKILL.md
@@ -6,7 +6,7 @@ compatibility: Requires openspec CLI.
 metadata:
   author: openspec
   version: "1.0"
-  generatedBy: "1.3.0"
+  generatedBy: "1.1.1"
 ---
 
 Verify that an implementation matches the change artifacts (specs, tasks, design).
diff --git a/.gitignore b/.gitignore
index 3346c46..482587a 100644
--- a/.gitignore
+++ b/.gitignore
@@ -43,3 +43,22 @@ packages/ksef-client-ts/docs/public/open-api.json
 
 # markdown-vault MCP cache
 packages/ksef-client-ts/docs/.markdown_vault_mcp/
+
+# macOS
+.DS_Store
+
+# Editor / OS noise
+*.swp
+*~
+Thumbs.db
+
+# Logs
+*.log
+yarn-debug.log*
+yarn-error.log*
+npm-debug.log*
+
+# Environment / secrets
+.env
+.env.*
+!.env.example

From 1e46f55991ff39b4597ff0361498fc903c82e0fe Mon Sep 17 00:00:00 2001
From: Flop Butylkin <flopspm@gmail.com>
Date: Mon, 6 Jul 2026 00:07:15 +0200
Subject: [PATCH 3/4] feat(pdf): render invoices & UPO to PDF via optional
 ksef-client-ts/pdf subpath

Add a node-only `ksef-client-ts/pdf` subpath that renders FA(2)/FA(3) invoices
and UPO(4.2)/(4.3) receipts to PDF from a template-driven block DSL, with
pl/en/pl+en labels and automatic KSeF Code I QR whose hash is taken over the
original input bytes. pdfmake is an optional peer (^0.2.20), lazily loaded, so
the core install stays clean and `./pdf` imports never pull it in.

Also adds the `ksef invoice pdf` CLI command, built-in templates for each
supported version, i18n bundles, a verification harness (attw / publint /
pdf-types / cold-subpath across the Node 18/20/22 matrix), a how-to guide, and
the OpenSpec spec for the new invoice-pdf-render capability.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EaMDwzgFf8zzWn7mM1Tjq5
---
 .github/workflows/ci.yml                      |  18 +
 README.md                                     |   1 +
 openspec/specs/cli-invoice/spec.md            |  66 +-
 openspec/specs/invoice-pdf-render/spec.md     | 212 +++++
 packages/ksef-client-ts/CHANGELOG.md          |   3 +
 .../ksef-client-ts/docs/.vitepress/config.ts  |   1 +
 packages/ksef-client-ts/docs/index.md         |   2 +
 packages/ksef-client-ts/docs/pdf-export.md    | 302 ++++++
 packages/ksef-client-ts/package.json          |  22 +-
 .../ksef-client-ts/scripts/check-pdf-cold.mjs |  69 ++
 .../src/cli/commands/invoice.ts               |  76 +-
 packages/ksef-client-ts/src/pdf/accessor.ts   |  97 ++
 packages/ksef-client-ts/src/pdf/errors.ts     |  13 +
 packages/ksef-client-ts/src/pdf/fonts.ts      | 110 +++
 packages/ksef-client-ts/src/pdf/format.ts     |  62 ++
 packages/ksef-client-ts/src/pdf/i18n/en.ts    |  37 +
 packages/ksef-client-ts/src/pdf/i18n/index.ts |  50 +
 packages/ksef-client-ts/src/pdf/i18n/pl.ts    |  43 +
 packages/ksef-client-ts/src/pdf/i18n/types.ts |  11 +
 packages/ksef-client-ts/src/pdf/index.ts      | 195 ++++
 packages/ksef-client-ts/src/pdf/parse.ts      |  66 ++
 .../src/pdf/pdfmake-modules.d.ts              |  11 +
 packages/ksef-client-ts/src/pdf/qr.ts         |  72 ++
 .../src/pdf/template/blocks/annotations.ts    |  23 +
 .../src/pdf/template/blocks/footer.ts         |  16 +
 .../src/pdf/template/blocks/header.ts         |  33 +
 .../src/pdf/template/blocks/image.ts          |  14 +
 .../src/pdf/template/blocks/index.ts          |  31 +
 .../src/pdf/template/blocks/lines.ts          |  30 +
 .../src/pdf/template/blocks/parties.ts        |  22 +
 .../src/pdf/template/blocks/payment.ts        |  24 +
 .../src/pdf/template/blocks/qr.ts             |  14 +
 .../src/pdf/template/blocks/table.ts          |  45 +
 .../src/pdf/template/blocks/totals.ts         |  29 +
 .../src/pdf/template/builtin/fa2-default.json |  81 ++
 .../src/pdf/template/builtin/fa3-default.json |  81 ++
 .../src/pdf/template/builtin/index.ts         |  26 +
 .../src/pdf/template/builtin/upo-4_2.json     |  43 +
 .../src/pdf/template/builtin/upo-4_3.json     |  43 +
 .../ksef-client-ts/src/pdf/template/dsl.ts    | 311 ++++++
 .../src/pdf/template/interpret.ts             | 175 ++++
 .../tests/fixtures/pdf-types-check.ts         |  41 +
 .../ksef-client-ts/tests/fixtures/pdf/fa2.xml |  75 ++
 .../ksef-client-ts/tests/fixtures/pdf/fa3.xml |  75 ++
 .../tests/fixtures/pdf/upo-4_2.xml            |  24 +
 .../tests/fixtures/pdf/upo-4_3.xml            |  24 +
 .../unit/cli/commands/invoice-pdf.test.ts     | 186 ++++
 .../tests/unit/pdf/accessor.test.ts           | 242 +++++
 .../tests/unit/pdf/blocks-primitive.test.ts   | 150 +++
 .../tests/unit/pdf/blocks-semantic.test.ts    | 383 ++++++++
 .../ksef-client-ts/tests/unit/pdf/dsl.test.ts | 138 +++
 .../tests/unit/pdf/errors.test.ts             |  20 +
 .../tests/unit/pdf/fonts-loader.test.ts       |  37 +
 .../tests/unit/pdf/fonts.test.ts              |  65 ++
 .../tests/unit/pdf/format.test.ts             | 117 +++
 .../tests/unit/pdf/i18n.test.ts               |  64 ++
 .../tests/unit/pdf/interpret.test.ts          | 336 +++++++
 .../tests/unit/pdf/parse.test.ts              | 154 +++
 .../ksef-client-ts/tests/unit/pdf/qr.test.ts  | 146 +++
 .../tests/unit/pdf/render-builtins.test.ts    |  59 ++
 .../tests/unit/pdf/render-smoke.test.ts       |  69 ++
 .../ksef-client-ts/tsconfig.pdf-check.json    |  12 +
 packages/ksef-client-ts/tsup.config.ts        |   7 +-
 yarn.lock                                     | 887 +++++++++++++++++-
 64 files changed, 5877 insertions(+), 14 deletions(-)
 create mode 100644 openspec/specs/invoice-pdf-render/spec.md
 create mode 100644 packages/ksef-client-ts/docs/pdf-export.md
 create mode 100644 packages/ksef-client-ts/scripts/check-pdf-cold.mjs
 create mode 100644 packages/ksef-client-ts/src/pdf/accessor.ts
 create mode 100644 packages/ksef-client-ts/src/pdf/errors.ts
 create mode 100644 packages/ksef-client-ts/src/pdf/fonts.ts
 create mode 100644 packages/ksef-client-ts/src/pdf/format.ts
 create mode 100644 packages/ksef-client-ts/src/pdf/i18n/en.ts
 create mode 100644 packages/ksef-client-ts/src/pdf/i18n/index.ts
 create mode 100644 packages/ksef-client-ts/src/pdf/i18n/pl.ts
 create mode 100644 packages/ksef-client-ts/src/pdf/i18n/types.ts
 create mode 100644 packages/ksef-client-ts/src/pdf/index.ts
 create mode 100644 packages/ksef-client-ts/src/pdf/parse.ts
 create mode 100644 packages/ksef-client-ts/src/pdf/pdfmake-modules.d.ts
 create mode 100644 packages/ksef-client-ts/src/pdf/qr.ts
 create mode 100644 packages/ksef-client-ts/src/pdf/template/blocks/annotations.ts
 create mode 100644 packages/ksef-client-ts/src/pdf/template/blocks/footer.ts
 create mode 100644 packages/ksef-client-ts/src/pdf/template/blocks/header.ts
 create mode 100644 packages/ksef-client-ts/src/pdf/template/blocks/image.ts
 create mode 100644 packages/ksef-client-ts/src/pdf/template/blocks/index.ts
 create mode 100644 packages/ksef-client-ts/src/pdf/template/blocks/lines.ts
 create mode 100644 packages/ksef-client-ts/src/pdf/template/blocks/parties.ts
 create mode 100644 packages/ksef-client-ts/src/pdf/template/blocks/payment.ts
 create mode 100644 packages/ksef-client-ts/src/pdf/template/blocks/qr.ts
 create mode 100644 packages/ksef-client-ts/src/pdf/template/blocks/table.ts
 create mode 100644 packages/ksef-client-ts/src/pdf/template/blocks/totals.ts
 create mode 100644 packages/ksef-client-ts/src/pdf/template/builtin/fa2-default.json
 create mode 100644 packages/ksef-client-ts/src/pdf/template/builtin/fa3-default.json
 create mode 100644 packages/ksef-client-ts/src/pdf/template/builtin/index.ts
 create mode 100644 packages/ksef-client-ts/src/pdf/template/builtin/upo-4_2.json
 create mode 100644 packages/ksef-client-ts/src/pdf/template/builtin/upo-4_3.json
 create mode 100644 packages/ksef-client-ts/src/pdf/template/dsl.ts
 create mode 100644 packages/ksef-client-ts/src/pdf/template/interpret.ts
 create mode 100644 packages/ksef-client-ts/tests/fixtures/pdf-types-check.ts
 create mode 100644 packages/ksef-client-ts/tests/fixtures/pdf/fa2.xml
 create mode 100644 packages/ksef-client-ts/tests/fixtures/pdf/fa3.xml
 create mode 100644 packages/ksef-client-ts/tests/fixtures/pdf/upo-4_2.xml
 create mode 100644 packages/ksef-client-ts/tests/fixtures/pdf/upo-4_3.xml
 create mode 100644 packages/ksef-client-ts/tests/unit/cli/commands/invoice-pdf.test.ts
 create mode 100644 packages/ksef-client-ts/tests/unit/pdf/accessor.test.ts
 create mode 100644 packages/ksef-client-ts/tests/unit/pdf/blocks-primitive.test.ts
 create mode 100644 packages/ksef-client-ts/tests/unit/pdf/blocks-semantic.test.ts
 create mode 100644 packages/ksef-client-ts/tests/unit/pdf/dsl.test.ts
 create mode 100644 packages/ksef-client-ts/tests/unit/pdf/errors.test.ts
 create mode 100644 packages/ksef-client-ts/tests/unit/pdf/fonts-loader.test.ts
 create mode 100644 packages/ksef-client-ts/tests/unit/pdf/fonts.test.ts
 create mode 100644 packages/ksef-client-ts/tests/unit/pdf/format.test.ts
 create mode 100644 packages/ksef-client-ts/tests/unit/pdf/i18n.test.ts
 create mode 100644 packages/ksef-client-ts/tests/unit/pdf/interpret.test.ts
 create mode 100644 packages/ksef-client-ts/tests/unit/pdf/parse.test.ts
 create mode 100644 packages/ksef-client-ts/tests/unit/pdf/qr.test.ts
 create mode 100644 packages/ksef-client-ts/tests/unit/pdf/render-builtins.test.ts
 create mode 100644 packages/ksef-client-ts/tests/unit/pdf/render-smoke.test.ts
 create mode 100644 packages/ksef-client-ts/tsconfig.pdf-check.json

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 6962a25..cda6142 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -68,6 +68,24 @@ jobs:
       - name: Check /node entry types
         run: yarn check:node-types
 
+      # Proves the ./pdf public types resolve WITHOUT @types/pdfmake in scope —
+      # a consumer that has not installed pdfmake still type-checks ./pdf.
+      - name: Check /pdf entry types
+        run: yarn check:pdf-types
+
+      # Runs on every matrix Node (18/20/22): the ./pdf subpath imports/requires
+      # without eagerly loading pdfmake and never throws at module-load time.
+      - name: Check /pdf cold subpath
+        run: node packages/ksef-client-ts/scripts/check-pdf-cold.mjs
+
+      # Publish-correctness of the package exports (incl. the new ./pdf subpath).
+      # Runs once — the built dist is identical across the matrix.
+      - name: Check package exports (attw + publint)
+        if: matrix.node-version == 22
+        run: |
+          yarn check:attw
+          yarn check:publint
+
       - name: Check fs-free core bundles
         run: node packages/ksef-client-ts/scripts/check-fs-free-core.mjs
 
diff --git a/README.md b/README.md
index c23523c..e8467a5 100644
--- a/README.md
+++ b/README.md
@@ -19,6 +19,7 @@ TypeScript client for the Polish National e-Invoice System (KSeF) API v2.
 - **Multiple document structures** — FA, PEF, PEF_KOR, FA_RR with typed FormCode constants and UPO parsing
 - **Invoice XML serialization (FA2/FA3/PEF/PEF_KOR)** — build XSD-compliant invoice XML from typed TypeScript objects with correct element ordering (including the FA3 per-VAT-rate interleave) and namespace injection; `ksef invoice build` exposes the same pipeline to shell workflows with JSON/YAML input and optional XSD validation
 - **Invoice XML validation** — three-level client-side validation (well-formedness, XSD schema via Zod, NIP/PESEL checksums, future date rejection) with auto-detection for all 6 invoice types
+- **PDF visualization** — render FA(2)/FA(3) invoices and UPO(4.2)/(4.3) receipts to print-ready PDF offline from version-specific, declarative templates, with Polish/English/bilingual labels and the embedded KSeF Code I verification QR; `ksef invoice pdf` brings the same rendering to shell workflows. Requires the optional `pdfmake` peer (`npm i "pdfmake@^0.2.20"`), so the core install stays dependency-free
 - **Typed errors with RFC 7807 Problem Details** — `KSeFError` hierarchy with dedicated classes for 400/401/403/410/429 carrying structured diagnostic context; exhaustive dispatch via the `KSeFApiProblem` union and `assertNever`; fluent request builders
 - **Comprehensive test coverage** — unit + E2E tests across HTTP, crypto, services, workflows; CI on every change
 - **Interactive setup wizard** — `ksef setup` guides through environment selection, authentication, and token generation in one flow
diff --git a/openspec/specs/cli-invoice/spec.md b/openspec/specs/cli-invoice/spec.md
index 231921d..68ff9e7 100644
--- a/openspec/specs/cli-invoice/spec.md
+++ b/openspec/specs/cli-invoice/spec.md
@@ -1,5 +1,7 @@
-## MODIFIED Requirements
+## Purpose
 
+The `cli-invoice` capability defines the `ksef invoice` command group, which submits invoices to KSeF from the command line. It covers sending a single invoice XML file — reading the file, computing its hash and size, encrypting the content via the client crypto layer, and dispatching it through an active online session. It also handles form-code selection and optional pre-send schema validation.
+## Requirements
 ### Requirement: Send single invoice
 The CLI SHALL provide `ksef invoice send <file.xml>` to send a single invoice. The CLI MUST read the XML file, compute its hash and size, encrypt the content via `client.crypto`, and call `OnlineSessionService.sendInvoice()`. Crypto MUST be initialized automatically (`client.crypto.init()`). It MUST accept an optional `--form-code <key>` flag where `<key>` is one of `FA2`, `FA3`, `PEF3`, `PEFKOR3`, `FARR1`. It MUST accept an optional `--validate` flag that runs schema validation before sending.
 
@@ -34,3 +36,65 @@ The CLI SHALL provide `ksef invoice send <file.xml>` to send a single invoice. T
 #### Scenario: Send with validation passing
 - **WHEN** user runs `ksef invoice send invoice.xml --validate` and the XML is valid
 - **THEN** CLI proceeds with encryption and sending normally
+
+### Requirement: Render an invoice or UPO to PDF
+
+The CLI SHALL provide `ksef invoice pdf <file>` to render a KSeF invoice or UPO XML file to a PDF. The command MUST lazily bridge into the internal PDF module and, when `pdfmake` is not installed or is an incompatible version, MUST surface the module's friendly installation error (`npm i "pdfmake@^0.2.20"`) rather than a raw crash. By default the output PDF MUST be written next to the source file with a `.pdf` extension.
+
+The command MUST accept:
+- `--template <name>` — select a built-in template by name; mutually exclusive with `--template-file`.
+- `--template-file <path>` — load a custom `.json` template from a path; mutually exclusive with `--template`.
+- `--locale <pl|en|pl+en>` — label language, defaulting to `pl`.
+- `--out <file.pdf>` — output path override.
+- `--qr` — embed the KSeF Code I QR derived from the invoice XML.
+- `--ksef-number <NR>` — the KSeF number to print; when absent the visualization is marked OFFLINE.
+- `--upo` — treat the input as a UPO document (otherwise the version is auto-detected).
+- `--env <e>` — environment used to derive the QR base URL.
+
+When neither `--template` nor `--template-file` is given, the command MUST select the default built-in template matching the detected XML version.
+
+#### Scenario: Render an invoice with the default built-in template
+
+- **WHEN** user runs `ksef invoice pdf invoice.xml` with no template flag
+- **THEN** CLI detects the invoice version, renders it with the matching built-in template, and writes `invoice.pdf` next to the source file
+
+#### Scenario: Render with a built-in template by name
+
+- **WHEN** user runs `ksef invoice pdf invoice.xml --template fa3-default`
+- **THEN** CLI renders the invoice using the named built-in template
+
+#### Scenario: Render with a custom template file
+
+- **WHEN** user runs `ksef invoice pdf invoice.xml --template-file ./my-template.json`
+- **THEN** CLI loads the custom template from the path and renders the invoice
+
+#### Scenario: Mutually exclusive template flags
+
+- **WHEN** user runs `ksef invoice pdf invoice.xml --template fa3-default --template-file ./my-template.json`
+- **THEN** CLI SHALL display an error stating that `--template` and `--template-file` cannot be combined
+
+#### Scenario: Output path override
+
+- **WHEN** user runs `ksef invoice pdf invoice.xml --out /tmp/result.pdf`
+- **THEN** CLI writes the PDF to `/tmp/result.pdf` instead of next to the source file
+
+#### Scenario: Embed QR code
+
+- **WHEN** user runs `ksef invoice pdf invoice.xml --qr`
+- **THEN** CLI renders the PDF with the KSeF Code I QR derived from the invoice XML
+
+#### Scenario: Render a UPO document
+
+- **WHEN** user runs `ksef invoice pdf upo.xml --upo`
+- **THEN** CLI renders the UPO receipt using the matching built-in UPO template
+
+#### Scenario: pdfmake not installed
+
+- **WHEN** user runs `ksef invoice pdf invoice.xml` without `pdfmake` installed
+- **THEN** CLI SHALL display the friendly installation hint `npm i "pdfmake@^0.2.20"` rather than a raw module-not-found error
+
+#### Scenario: Localized labels
+
+- **WHEN** user runs `ksef invoice pdf invoice.xml --locale pl+en`
+- **THEN** CLI renders the PDF with bilingual Polish/English labels
+
diff --git a/openspec/specs/invoice-pdf-render/spec.md b/openspec/specs/invoice-pdf-render/spec.md
new file mode 100644
index 0000000..05e09ee
--- /dev/null
+++ b/openspec/specs/invoice-pdf-render/spec.md
@@ -0,0 +1,212 @@
+# invoice-pdf-render Specification
+
+## Purpose
+Render a KSeF invoice or UPO receipt XML into a PDF via the node-only `ksef-client-ts/pdf` subpath. The capability covers a template-driven block DSL (bindings, repeaters, conditions, formatters) over an accessor layer that smooths compact XML parsing, built-in version-specific templates for FA(2)/FA(3)/UPO(4.2)/UPO(4.3), `pl`/`en`/`pl+en` label localization, automatic KSeF Code I QR derivation whose hash is taken over the original input bytes, custom-template loading with validation and version matching, and an optional lazily-loaded `pdfmake` peer so the core install stays clean.
+## Requirements
+### Requirement: Render invoice XML to PDF via the `ksef-client-ts/pdf` subpath
+
+The library SHALL expose a node-only subpath entry point `ksef-client-ts/pdf` that renders a KSeF invoice XML document into a PDF and returns it as a `Uint8Array`. The entry point MUST accept the XML as either a `string` or a `Uint8Array`. The subpath MUST be isolated from the primary `.` entry point so that importing `.` never loads the PDF stack and never violates the fs-free invariant of `.`.
+
+#### Scenario: Render an FA(3) invoice to PDF bytes
+
+- **WHEN** a caller imports `renderInvoicePdf` from `ksef-client-ts/pdf` and calls it with a valid FA(3) XML and a built-in template name
+- **THEN** the call resolves to a non-empty `Uint8Array` whose bytes begin with `%PDF-` and end with `%%EOF`
+
+#### Scenario: Primary entry point stays free of the PDF stack
+
+- **WHEN** a consumer imports only the primary `.` entry point
+- **THEN** the PDF stack (and `pdfmake`) MUST NOT be loaded and the fs-free invariant of `.` MUST hold
+
+### Requirement: Three template-source entry points
+
+The module SHALL provide three separate render functions distinguished by template source, so the caller never has to disambiguate "is this a name or a path": a built-in template selected by name, a custom template loaded from a file path, and a custom template passed as a DSL object. The module SHALL additionally provide a dedicated UPO renderer.
+
+#### Scenario: Render with a built-in template by name
+
+- **WHEN** the caller invokes the by-name render function with `'fa3-default'`
+- **THEN** the module resolves the corresponding built-in template and renders the invoice
+
+#### Scenario: Render with a custom template from a file
+
+- **WHEN** the caller invokes the from-file render function with a path to a `.json` template
+- **THEN** the module reads the file, validates it, and renders the invoice
+
+#### Scenario: Render with a custom template object
+
+- **WHEN** the caller invokes the from-template render function with a DSL template object
+- **THEN** the module validates the object and renders the invoice without reading the filesystem
+
+### Requirement: Invoice and UPO version detection
+
+The module SHALL detect the document version from the XML. It MUST distinguish `FA(2)` and `FA(3)` invoices and `UPO(4.2)` and `UPO(4.3)` receipts, and MUST return a null-like result for unrecognized documents. FA(1) MUST NOT be supported.
+
+#### Scenario: Detect FA(3)
+
+- **WHEN** `detectInvoiceVersion` is called with an FA(3) invoice XML
+- **THEN** it returns `FA(3)`
+
+#### Scenario: Detect UPO version
+
+- **WHEN** `detectUpoVersion` is called with a UPO(4.3) receipt XML
+- **THEN** it returns `UPO(4.3)`
+
+#### Scenario: Unrecognized document
+
+- **WHEN** a version-detection function is called with XML that is neither a supported invoice nor a supported UPO
+- **THEN** it returns a null-like result rather than throwing
+
+### Requirement: Built-in templates for supported versions
+
+The module SHALL ship built-in templates for at least `fa2-default`, `fa3-default`, `upo-4_2`, and `upo-4_3`. Built-in templates MUST be bundled into the distributed output (not read from the filesystem at runtime).
+
+#### Scenario: Built-in template renders without runtime filesystem access
+
+- **WHEN** a built-in template is selected by name in an environment where the package's own template files are not readable from disk
+- **THEN** rendering still succeeds because the template is bundled into the distributed module
+
+#### Scenario: Built-in templates are self-consistent
+
+- **WHEN** each built-in template is rendered in strict mode against a fixture that populates every optional field
+- **THEN** rendering succeeds with no unresolved binding, so a typo in a built-in template's dot-path surfaces as an error rather than an empty string
+
+### Requirement: Template DSL interpretation
+
+The module SHALL interpret a declarative, version-specific block DSL into a PDF layout. The DSL MUST support semantic blocks and layout-primitive blocks, dot-path bindings into the parsed XML, repeaters that iterate a collection, conditions that show a block only when a field is present or truthy, and value formatters (money / date / number / nip). The DSL MUST NOT provide general scripting. Container blocks MUST nest recursively up to a bounded depth.
+
+#### Scenario: Repeater over invoice lines
+
+- **WHEN** a template contains a repeater block bound to the invoice-lines collection
+- **THEN** the interpreter emits one rendered row per line
+
+#### Scenario: Conditional block
+
+- **WHEN** a block declares a condition on a field that is absent
+- **THEN** the interpreter omits that block from the output
+
+#### Scenario: Value formatter
+
+- **WHEN** a binding declares a `money` formatter over a numeric field
+- **THEN** the rendered value is formatted as a monetary amount rather than the raw string
+
+#### Scenario: Nesting depth limit exceeded
+
+- **WHEN** a template nests container blocks beyond the allowed depth
+- **THEN** interpretation fails with a clear error
+
+### Requirement: Accessor layer over compact XML parsing
+
+Field access from templates SHALL go through an accessor layer that smooths compact-parse artifacts, not directly against the parsed object. A repeater's collection MUST always be read as an array, so a single-element collection that the parser collapsed into an object is handled identically to a multi-element collection. Field access MUST descend safely (a missing intermediate segment yields an absent value, not a throw), MUST unwrap mixed-content text nodes, and MUST support reading an attribute segment.
+
+#### Scenario: Single-line invoice does not break the repeater
+
+- **WHEN** an invoice has exactly one line and the parser collapsed the lines collection into a single object
+- **THEN** the repeater still iterates exactly once, as if the collection were an array
+
+#### Scenario: Safe descent through a missing field
+
+- **WHEN** a binding path descends through a segment that is absent in the document
+- **THEN** the accessor yields an empty/absent value without throwing (subject to strict mode)
+
+### Requirement: Missing-binding behavior is configurable via strict mode
+
+By default a missing binding SHALL resolve to an empty string, because KSeF invoices contain many optional fields. When strict mode is enabled, a missing binding MUST instead throw a clear error identifying the failing path.
+
+#### Scenario: Lenient default
+
+- **WHEN** a template binds a field that is absent and strict mode is not enabled
+- **THEN** the field renders as an empty string and rendering succeeds
+
+#### Scenario: Strict mode surfaces the missing path
+
+- **WHEN** a template binds a field that is absent and strict mode is enabled
+- **THEN** rendering fails with an error naming the missing binding path
+
+### Requirement: Multi-language labels
+
+The module SHALL support label localization in `pl`, `en`, and `pl+en`, selected per render call and defaulting to `pl`. Only `pl` and `en` label bundles are maintained; `pl+en` MUST be produced by concatenating the two with a configurable separator (defaulting to `' / '`). A custom template MAY override individual labels; a missing label key MUST fall back to `pl`.
+
+#### Scenario: English labels
+
+- **WHEN** a render is requested with locale `en`
+- **THEN** block labels are printed from the English bundle
+
+#### Scenario: Bilingual labels with a custom separator
+
+- **WHEN** a render is requested with locale `pl+en` and a newline separator
+- **THEN** each label prints the Polish and English text joined by the newline
+
+### Requirement: Automatic QR (Code I) derivation
+
+When QR output is requested, the module SHALL build the KSeF Code I verification URL from the invoice XML using the core verification-link service, and render it as a QR code in the PDF. The seller NIP and issue date used for the URL MAY be read from the parsed XML. The base verification URL MUST derive from an explicit override or from the selected environment, defaulting to production.
+
+#### Scenario: QR requested builds the same URL as the core service
+
+- **WHEN** QR output is requested for an invoice
+- **THEN** the URL encoded in the QR equals the URL the core verification-link service produces for the same NIP, issue date, and hash
+
+#### Scenario: QR disabled
+
+- **WHEN** QR output is not requested
+- **THEN** no QR code is rendered and no verification URL is built
+
+### Requirement: QR hash is computed over the original input bytes
+
+The invoice hash used for the QR verification URL SHALL be computed over the original input bytes, bypassing the XML parser and any normalization. Field extraction and hashing MUST be two independent consumptions of the input. A `Uint8Array` input MUST be hashed directly. A `string` input MUST be hashed as its UTF-8 bytes with no BOM stripping, re-encoding, or line-ending normalization. A caller-supplied canonical hash MUST be used verbatim without recomputation.
+
+#### Scenario: Byte-identical inputs produce the same hash
+
+- **WHEN** the same document is rendered once as a `Uint8Array` and once as the equivalent UTF-8 `string` with no BOM and no reformatting
+- **THEN** both produce the same QR hash
+
+#### Scenario: Byte-level changes change the hash
+
+- **WHEN** the same logical document is hashed with an added BOM, CRLF line endings, or pretty-printing
+- **THEN** the resulting hash differs, proving the hash is taken over raw bytes rather than reparsed XML
+
+#### Scenario: Caller-supplied hash overrides recomputation
+
+- **WHEN** a caller passes a known canonical hash
+- **THEN** the module uses it verbatim and does not recompute a hash from the input
+
+### Requirement: Custom template validation and version matching
+
+The module SHALL validate custom templates before rendering. An unknown block type or structurally invalid template MUST produce a clear error. A template whose declared schema does not match the detected XML version MUST be rejected with a version-mismatch error.
+
+#### Scenario: Unknown block type
+
+- **WHEN** a custom template contains an unknown block type
+- **THEN** validation fails with a clear error identifying the problem
+
+#### Scenario: Template/version mismatch
+
+- **WHEN** an FA(2) template is used to render an FA(3) invoice
+- **THEN** the module rejects the render with a version-mismatch error
+
+### Requirement: Optional `pdfmake` peer dependency loaded lazily
+
+The module SHALL treat `pdfmake` as an optional peer dependency pinned to `^0.2.20` and load it lazily only when a render function is called. Importing or requiring the subpath without `pdfmake` installed MUST NOT throw; the absence MUST surface only on a render call, as a friendly error advising `npm i "pdfmake@^0.2.20"`. After the lazy load, the module MUST verify the resolved `pdfmake` version satisfies `^0.2.20` and MUST reject an incompatible version (including 0.3.x) with a clear error. The subpath's public types MUST NOT require consumers to have `pdfmake` types installed.
+
+#### Scenario: Import without pdfmake does not throw
+
+- **WHEN** the subpath is imported (ESM) or required (CJS) while `pdfmake` is not installed
+- **THEN** the module loads successfully and does not throw at import/require time
+
+#### Scenario: Render without pdfmake gives a friendly error
+
+- **WHEN** a render function is called while `pdfmake` is not installed
+- **THEN** the call fails with a friendly error advising installation of `pdfmake@^0.2.20`, not a raw module-not-found or transitive-dependency crash
+
+#### Scenario: Incompatible pdfmake version is rejected
+
+- **WHEN** a render function is called with an installed `pdfmake` version outside `^0.2.20` (for example 0.3.x)
+- **THEN** the call fails with a clear error stating the required range and the version found
+
+### Requirement: Render UPO receipts to PDF
+
+The module SHALL render UPO(4.2) and UPO(4.3) receipt XML to a PDF using the same engine and the built-in UPO templates.
+
+#### Scenario: Render a UPO receipt
+
+- **WHEN** the UPO render function is called with a valid UPO receipt XML
+- **THEN** it resolves to a non-empty `Uint8Array` beginning with `%PDF-`
+
diff --git a/packages/ksef-client-ts/CHANGELOG.md b/packages/ksef-client-ts/CHANGELOG.md
index 19af62d..c7232f7 100644
--- a/packages/ksef-client-ts/CHANGELOG.md
+++ b/packages/ksef-client-ts/CHANGELOG.md
@@ -6,6 +6,9 @@ All notable changes to this project will be documented in this file.
 
 ### Added
 
+- **Invoice and receipt PDF export** — render KSeF invoices and their official UPO receipts to print-ready PDF documents offline, with Polish, English, or bilingual labels, an embedded KSeF verification code, and a choice of ready-made layouts or your own custom templates, also available from the command line.
+- **Optional PDF engine, kept out of the core install** — PDF rendering relies on an optional add-on that is not pulled in automatically, so installing the library adds no extra dependencies until you opt into PDF output.
+
 ### Fixed
 
 ## [0.10.0] - 2026-06-15
diff --git a/packages/ksef-client-ts/docs/.vitepress/config.ts b/packages/ksef-client-ts/docs/.vitepress/config.ts
index d1ea8b9..3e1dc26 100644
--- a/packages/ksef-client-ts/docs/.vitepress/config.ts
+++ b/packages/ksef-client-ts/docs/.vitepress/config.ts
@@ -72,6 +72,7 @@ export default defineConfig({
           { text: 'Polish Holidays', link: '/polish-holidays' },
           { text: 'Validation', link: '/validation' },
           { text: 'XML Serialization', link: '/xml-serialization' },
+          { text: 'PDF Export', link: '/pdf-export' },
           { text: 'Error Handling', link: '/error-handling' },
           { text: 'External Signing', link: '/external-signing' },
           { text: 'Models & Types', link: '/models' },
diff --git a/packages/ksef-client-ts/docs/index.md b/packages/ksef-client-ts/docs/index.md
index 76c2a1e..9c87a3a 100644
--- a/packages/ksef-client-ts/docs/index.md
+++ b/packages/ksef-client-ts/docs/index.md
@@ -44,6 +44,8 @@ features:
     details: Build XSD-compliant FA2, FA3, PEF, and PEF_KOR XML from typed TypeScript objects. Correct element ordering (including the FA3 per-VAT-rate P_13/P_14/P_14W interleave), natural P_* sort, automatic namespace injection, and pass-through for pre-built XML strings and buffers. The `ksef invoice build` CLI wraps the same pipeline for JSON or YAML input with optional Zod and XSD validation.
   - title: Invoice XML Validation
     details: Three-level client-side validation against official KSeF XSD schemas — well-formedness, schema structure (via generated Zod validators), and business rules (NIP/PESEL checksums, future date rejection). Supports all 6 invoice types with auto-detection. CLI batch validation, programmatic API, and opt-in pre-send validation in workflows.
+  - title: PDF Visualization
+    details: Render FA (2)/(3) invoices and UPO (4.2)/(4.3) receipts to print-ready PDF offline from version-specific, declarative templates — Polish, English, or bilingual labels, an embedded KSeF Code I verification QR, and built-in or custom layouts. The `ksef invoice pdf` CLI brings the same rendering to shell workflows. PDF output uses the optional `pdfmake` peer (`npm i "pdfmake@^0.2.20"`), so the core install stays dependency-free.
   - title: Typed Errors with RFC 7807 Problem Details
     details: KSeFError hierarchy with dedicated classes for 400, 401, 403, 410, and 429 carrying structured diagnostic context (trace IDs, required-vs-present permissions, validation error lists). Exhaustive dispatch via the KSeFApiProblem union and assertNever helper. Fluent request builders catch mistakes at compile time before they hit the network.
   - title: Comprehensive Test Coverage
diff --git a/packages/ksef-client-ts/docs/pdf-export.md b/packages/ksef-client-ts/docs/pdf-export.md
new file mode 100644
index 0000000..1d8493c
--- /dev/null
+++ b/packages/ksef-client-ts/docs/pdf-export.md
@@ -0,0 +1,302 @@
+# PDF Export
+
+Render KSeF invoice and UPO receipt XML to a print-ready PDF, entirely offline, from a declarative template. Covers installing the optional `pdfmake` peer, the render functions, choosing and authoring a template, labels and locales, the verification QR code, and the CLI command.
+
+---
+
+## Overview
+
+The `ksef-client-ts/pdf` subpath turns a KSeF document (invoice or UPO receipt) into a PDF visualization. Rendering is driven by a **template** — a declarative JSON block layout that maps XML fields onto page elements — so the visual output is fully customizable without touching library code.
+
+The PDF layer handles two concerns:
+
+1. **Layout** — a version-specific template describes the page as a tree of semantic blocks (header, parties, lines, totals, …) and primitives (text, columns, table, …).
+2. **Rendering** — the template is interpreted into a PDF document and returned as raw bytes (`Uint8Array`) that you write to disk or stream to a client.
+
+Supported documents:
+
+| Document | Versions | Default built-in template |
+|----------|----------|---------------------------|
+| Standard invoice | `FA(2)`, `FA(3)` | `fa2-default`, `fa3-default` |
+| UPO receipt | `UPO(4.2)`, `UPO(4.3)` | `upo-4_2`, `upo-4_3` |
+
+`FA(1)` is not supported.
+
+::: tip Node-only subpath
+`ksef-client-ts/pdf` is a Node.js subpath — it reads bytes and returns bytes, and is not part of the fs-free core entry point. Importing it never pulls `pdfmake` into your bundle; the dependency is loaded lazily only when a render function actually runs.
+:::
+
+---
+
+## Install the pdfmake peer
+
+PDF rendering uses [`pdfmake`](https://www.npmjs.com/package/pdfmake) as an **optional peer dependency**. It is never installed automatically, so the core `ksef-client-ts` install stays dependency-free. To enable PDF output, install it explicitly:
+
+```bash
+npm i "pdfmake@^0.2.20"
+```
+
+Pin the `^0.2.20` range. **pdfmake 0.3.x is not supported** (its import and font-storage shape differ). Importing `ksef-client-ts/pdf` without `pdfmake` present still succeeds — only calling a render function throws a friendly, actionable install error:
+
+```text
+PDF rendering requires the optional peer dependency "pdfmake" (^0.2.20),
+which is not installed. Install it with: npm i "pdfmake@^0.2.20"
+```
+
+---
+
+## Render functions
+
+All four render functions accept the XML as a `string` or a `Uint8Array`, take an optional `RenderOptions` object, and resolve to a `Uint8Array` of PDF bytes.
+
+> Passing the **raw file bytes** (`Uint8Array`) rather than a decoded string is recommended when embedding the QR code: the verification hash is computed over the original bytes, so it matches the value registered by KSeF exactly.
+
+### `renderInvoicePdf(xml, name, opts?)` — built-in template
+
+Render an invoice with one of the built-in templates, selected by name.
+
+```ts
+import { readFile, writeFile } from 'node:fs/promises';
+import { renderInvoicePdf } from 'ksef-client-ts/pdf';
+
+const xml = await readFile('invoice.xml'); // Buffer is a Uint8Array
+const pdf = await renderInvoicePdf(xml, 'fa3-default', { locale: 'pl+en', qr: true });
+await writeFile('invoice.pdf', pdf);
+```
+
+### `renderInvoicePdfFromFile(xml, path, opts?)` — custom template file
+
+Render with a custom template loaded from a `.json` file. The template is validated before rendering; a structural problem throws with a path-tagged message.
+
+```ts
+import { renderInvoicePdfFromFile } from 'ksef-client-ts/pdf';
+
+const pdf = await renderInvoicePdfFromFile(xml, './templates/my-invoice.json', {
+  locale: 'pl',
+});
+```
+
+### `renderInvoicePdfFromTemplate(xml, template, opts?)` — custom template object
+
+Render with a template you build in code (for example, generated at runtime).
+
+```ts
+import { renderInvoicePdfFromTemplate, type InvoiceTemplate } from 'ksef-client-ts/pdf';
+
+const template: InvoiceTemplate = {
+  schema: 'FA(3)',
+  blocks: [
+    { type: 'header', title: { label: 'invoice' }, number: 'Fa.P_2', date: 'Fa.P_1' },
+    { type: 'totals', rows: [{ label: 'totalDue', path: 'Fa.P_15', format: 'money' }] },
+  ],
+};
+
+const pdf = await renderInvoicePdfFromTemplate(xml, template);
+```
+
+### `renderUpoPdf(xml, opts?)` — UPO receipt
+
+Render a UPO receipt. The version (`UPO(4.2)` / `UPO(4.3)`) is auto-detected and the matching built-in template is used.
+
+```ts
+import { renderUpoPdf } from 'ksef-client-ts/pdf';
+
+const pdf = await renderUpoPdf(await readFile('upo.xml'));
+```
+
+### Version detection helpers
+
+`detectInvoiceVersion` and `detectUpoVersion` inspect the XML and return the detected version or `null`.
+
+```ts
+import { detectInvoiceVersion, detectUpoVersion } from 'ksef-client-ts/pdf';
+
+detectInvoiceVersion(xml); // 'FA(2)' | 'FA(3)' | null
+detectUpoVersion(xml);     // 'UPO(4.2)' | 'UPO(4.3)' | null
+```
+
+---
+
+## Render options
+
+`RenderOptions` (all optional) is the last argument of every render function:
+
+| Option | Type | Purpose |
+|--------|------|---------|
+| `locale` | `'pl' \| 'en' \| 'pl+en'` | Label language. Default `'pl'`. |
+| `qr` | `boolean` | Embed the KSeF Code I verification QR derived from the invoice XML. |
+| `ksefNumber` | `string` | KSeF number printed on the visualization; when absent the document is marked **OFFLINE**. |
+| `env` | `'prod' \| 'test' \| 'demo'` | Environment used to derive the QR base URL. Default `'prod'`. |
+| `baseQrUrl` | `string` | Override the QR base URL (offline / non-standard). |
+| `logo` | `string` | Logo image as a `data:` URI. |
+| `theme` | `{ accent?: string }` | Accent colour. |
+| `bilingualSeparator` | `string` | Separator for the `pl+en` locale. Default `' / '`. |
+| `strict` | `boolean` | Throw on a missing binding instead of rendering an empty string. |
+| `invoiceHash` | `string` | Precomputed canonical invoice hash (base64), used verbatim for the QR. |
+
+---
+
+## Templates
+
+A template is a declarative JSON document. It is deliberately **not** a scripting language — there are blocks, field bindings, conditions, repeaters, and formatters, and nothing else. Custom layouts compose the built-in blocks rather than register code.
+
+### Structure
+
+```text
+{
+  "schema":       "FA(3)",          // targets one XML kind (required)
+  "page":         { … },            // size, orientation, margins
+  "defaultStyle": { … },            // pdfmake style props applied everywhere
+  "styles":       { "title": … },   // named, reusable style bags
+  "labels":       { "seller": … },  // per-template label overrides
+  "blocks":       [ … ]             // the page content (required)
+}
+```
+
+The `schema` field binds a template to a single document kind. If you render an `FA(2)` document with an `FA(3)` template (or vice versa), the engine rejects the mismatch rather than producing a broken PDF.
+
+### Blocks
+
+**Semantic blocks** carry meaning and lay themselves out:
+
+| Block | Renders |
+|-------|---------|
+| `header` | Title, invoice number, date, optional logo |
+| `parties` | Seller / buyer two-column panel |
+| `lines` | Invoice line-item table |
+| `totals` | Net / VAT / gross summary rows |
+| `payment` | Payment details (amount paid, date, method) |
+| `annotations` | Miscellaneous labelled fields |
+| `qr` | The verification QR image |
+| `footer` | Footer note |
+
+**Primitive blocks** are layout building blocks: `text`, `columns`, `stack`, `table`, `image`, `divider`, `spacer`.
+
+### Bindings, labels, conditions, and formats
+
+- **Binding paths** are dot-paths into the document body — e.g. `Fa.P_2` (invoice number), `Podmiot1.DaneIdentyfikacyjne.Nazwa` (seller name). Paths are relative to the body element, not the document wrapper.
+- **`label`** references an i18n label key resolved per locale; **`text`** is a literal string printed as-is.
+- **`when`** conditionally renders a block against a presence test. It accepts a binding path (e.g. `Fa.Platnosc`) or a context flag: `qr`, `offline`, `hasKsefNumber`.
+- **`format`** names a value formatter: `money`, `date`, `number`, or `nip`.
+
+### Minimal example
+
+A trimmed `FA(3)` template with a header, a seller/buyer panel, a line table, a total, and a conditional QR:
+
+```json
+{
+  "schema": "FA(3)",
+  "page": { "size": "A4", "margins": [40, 40, 40, 50] },
+  "styles": {
+    "title": { "fontSize": 20, "bold": true },
+    "muted": { "color": "#666666", "fontSize": 8 }
+  },
+  "blocks": [
+    { "type": "header", "title": { "label": "invoice" }, "number": "Fa.P_2", "date": "Fa.P_1" },
+    { "type": "divider" },
+    {
+      "type": "parties",
+      "left":  { "label": "seller", "fields": ["Podmiot1.DaneIdentyfikacyjne.Nazwa", "Podmiot1.DaneIdentyfikacyjne.NIP"] },
+      "right": { "label": "buyer",  "fields": ["Podmiot2.DaneIdentyfikacyjne.Nazwa", "Podmiot2.DaneIdentyfikacyjne.NIP"] }
+    },
+    {
+      "type": "lines",
+      "from": "Fa.FaWiersz",
+      "columns": [
+        { "label": "name", "path": "P_7" },
+        { "label": "qty",  "path": "P_8B", "format": "number" },
+        { "label": "net",  "path": "P_11", "format": "money" }
+      ]
+    },
+    {
+      "type": "totals",
+      "rows": [{ "label": "totalDue", "path": "Fa.P_15", "format": "money" }]
+    },
+    { "type": "qr", "when": "qr", "fit": 90 },
+    { "type": "footer", "text": "ksef-client-ts", "style": "muted" }
+  ]
+}
+```
+
+The bundled `fa3-default` template is a good, complete starting point to copy and adapt.
+
+---
+
+## Locales
+
+Labels are localizable, driven by the `locale` option:
+
+| Locale | Output |
+|--------|--------|
+| `pl` (default) | Polish labels |
+| `en` | English labels |
+| `pl+en` | Both, concatenated per label |
+
+For `pl+en`, each label is the Polish and English text joined by `bilingualSeparator` (default `' / '`). A template can also override individual labels via its `labels` map — useful for company-specific wording.
+
+```ts
+const pdf = await renderInvoicePdf(xml, 'fa3-default', {
+  locale: 'pl+en',
+  bilingualSeparator: ' | ',
+});
+```
+
+---
+
+## Verification QR (Code I)
+
+Set `qr: true` to embed the KSeF **Code I** verification QR. It is derived automatically from the invoice XML — you do not supply a URL. The verification hash is computed over the original invoice bytes so it matches the value KSeF registered. Use `env` to pick the correct portal (`prod` by default), or `baseQrUrl` to override it for offline / non-standard cases.
+
+```ts
+const pdf = await renderInvoicePdf(xml, 'fa3-default', {
+  qr: true,
+  env: 'test',
+  ksefNumber: '1234567890-20260705-ABCDEF012345-01',
+});
+```
+
+When no `ksefNumber` is provided the visualization is marked **OFFLINE**. UPO receipts do not carry a QR code.
+
+---
+
+## CLI
+
+The same rendering is available from the command line:
+
+```bash
+ksef invoice pdf invoice.xml
+```
+
+By default the invoice version is auto-detected and the matching built-in template (`fa2-default` / `fa3-default`) is used; UPO documents are auto-detected too. The PDF is written next to the source file with a `.pdf` extension.
+
+```bash
+# Built-in template, bilingual labels, with QR
+ksef invoice pdf invoice.xml --locale pl+en --qr --ksef-number 1234567890-20260705-ABCDEF012345-01
+
+# Custom template, explicit output path
+ksef invoice pdf invoice.xml --template-file ./templates/my-invoice.json --out ./out/invoice.pdf
+
+# UPO receipt (auto-detected, or force with --upo)
+ksef invoice pdf upo.xml --upo
+```
+
+| Flag | Description |
+|------|-------------|
+| `--template <name>` | Built-in template name (mutually exclusive with `--template-file`) |
+| `--template-file <path>` | Custom JSON template path (mutually exclusive with `--template`) |
+| `--locale <pl\|en\|pl+en>` | Label language (default `pl`) |
+| `--qr` | Embed the KSeF Code I QR derived from the XML |
+| `--ksef-number <number>` | KSeF number to print (absent → marked OFFLINE) |
+| `--upo` | Treat the input as a UPO document (otherwise auto-detected) |
+| `--env <prod\|test\|demo>` | Environment for the QR base URL |
+| `--out <path>` | Output PDF path (default: alongside the source) |
+
+`--template` and `--template-file` are mutually exclusive — pass at most one. If `pdfmake` is not installed, the command exits with the same friendly install hint shown above.
+
+---
+
+## See also
+
+- [QR Codes & Verification Links](./qr-codes.md) — the Code I / Code II verification URLs behind the embedded QR.
+- [XML Serialization](./xml-serialization.md) — build the invoice XML that feeds the PDF renderer.
+- [CLI](./cli.md) — the full command reference.
diff --git a/packages/ksef-client-ts/package.json b/packages/ksef-client-ts/package.json
index ef4d1c0..744ade3 100644
--- a/packages/ksef-client-ts/package.json
+++ b/packages/ksef-client-ts/package.json
@@ -27,6 +27,16 @@
         "types": "./dist/node.d.cts",
         "default": "./dist/node.cjs"
       }
+    },
+    "./pdf": {
+      "import": {
+        "types": "./dist/pdf/index.d.ts",
+        "default": "./dist/pdf/index.js"
+      },
+      "require": {
+        "types": "./dist/pdf/index.d.cts",
+        "default": "./dist/pdf/index.cjs"
+      }
     }
   },
   "bin": {
@@ -45,6 +55,9 @@
     "test:watch": "vitest",
     "lint": "tsc --noEmit",
     "check:node-types": "tsc --project tsconfig.node-check.json",
+    "check:pdf-types": "tsc --project tsconfig.pdf-check.json",
+    "check:attw": "attw --pack . --profile node16",
+    "check:publint": "publint",
     "lint:md": "markdownlint-cli2",
     "lint:md:fix": "markdownlint-cli2 --fix",
     "link": "npm link",
@@ -101,14 +114,19 @@
     "zod": "^4.3.6"
   },
   "peerDependencies": {
-    "libxmljs2": "^0.37.0"
+    "libxmljs2": "^0.37.0",
+    "pdfmake": "^0.2.20"
   },
   "peerDependenciesMeta": {
     "libxmljs2": {
       "optional": true
+    },
+    "pdfmake": {
+      "optional": true
     }
   },
   "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.4",
     "@scalar/api-reference": "^1.49.3",
     "@types/node": "^22.13.10",
     "@types/node-forge": "^1.3.11",
@@ -121,6 +139,8 @@
     "jszip": "^3.10.1",
     "libxmljs2": "^0.37.0",
     "markdownlint-cli2": "^0.22.1",
+    "pdfmake": "^0.2.20",
+    "publint": "^0.3.12",
     "tsup": "^8.4.0",
     "typescript": "^5.8.2",
     "vitepress": "^1.6.4",
diff --git a/packages/ksef-client-ts/scripts/check-pdf-cold.mjs b/packages/ksef-client-ts/scripts/check-pdf-cold.mjs
new file mode 100644
index 0000000..351397a
--- /dev/null
+++ b/packages/ksef-client-ts/scripts/check-pdf-cold.mjs
@@ -0,0 +1,69 @@
+/**
+ * Verifies the `ksef-client-ts/pdf` subpath is a "cold" module against the built
+ * dist:
+ *   1. No top-level `require("pdfmake")` in the CJS build (must stay a lazy `import()`).
+ *   2. Requiring/importing the subpath does NOT eagerly load pdfmake.
+ *   3. Import/require never throws at module-load time (pdfmake absence surfaces
+ *      only when a `render*` function is called).
+ *
+ * Run after `yarn build`. Exits non-zero on any violation.
+ */
+import { createRequire } from 'node:module';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import path from 'node:path';
+
+const pkgDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const cjsPath = path.join(pkgDir, 'dist/pdf/index.cjs');
+const esmPath = path.join(pkgDir, 'dist/pdf/index.js');
+
+let failures = 0;
+const fail = (m) => {
+  console.error('✗', m);
+  failures++;
+};
+const ok = (m) => console.log('✓', m);
+
+// 1) The CJS build must not statically require pdfmake — it must stay dynamic.
+const cjs = readFileSync(cjsPath, 'utf8');
+if (/(^|[^.\w])require\(\s*["']pdfmake/m.test(cjs)) {
+  fail('dist/pdf/index.cjs has a top-level require("pdfmake") — it must be a lazy import()');
+} else {
+  ok('no top-level require("pdfmake") in dist/pdf/index.cjs');
+}
+
+const require = createRequire(import.meta.url);
+const pdfmakeLoaded = () =>
+  Object.keys(require.cache).some((k) => k.includes(`${path.sep}pdfmake${path.sep}`));
+
+// 2 & 3) CJS require succeeds, exports render functions, and does not load pdfmake.
+const before = pdfmakeLoaded();
+const cjsMod = require(cjsPath);
+if (typeof cjsMod.renderInvoicePdf !== 'function') {
+  fail('CJS build did not export renderInvoicePdf');
+} else {
+  ok('CJS require of ./pdf succeeds and exports render functions');
+}
+if (!before && pdfmakeLoaded()) {
+  fail('requiring ./pdf eagerly loaded pdfmake (not a cold module)');
+} else {
+  ok('requiring ./pdf did not load pdfmake (cold module)');
+}
+
+// ESM import must also succeed without throwing.
+try {
+  const esmMod = await import(pathToFileURL(esmPath).href);
+  if (typeof esmMod.renderInvoicePdf !== 'function') {
+    fail('ESM build did not export renderInvoicePdf');
+  } else {
+    ok('ESM import of ./pdf succeeds');
+  }
+} catch (err) {
+  fail(`ESM import of ./pdf threw at load time: ${err.message}`);
+}
+
+if (failures > 0) {
+  console.error(`\n${failures} cold-subpath check(s) failed.`);
+  process.exit(1);
+}
+console.log('\nAll cold-subpath checks passed.');
diff --git a/packages/ksef-client-ts/src/cli/commands/invoice.ts b/packages/ksef-client-ts/src/cli/commands/invoice.ts
index 2b1a30d..9aff05d 100644
--- a/packages/ksef-client-ts/src/cli/commands/invoice.ts
+++ b/packages/ksef-client-ts/src/cli/commands/invoice.ts
@@ -570,7 +570,81 @@ const validateCmd = defineCommand({
   },
 });
 
+const VALID_PDF_LOCALES = ['pl', 'en', 'pl+en'] as const;
+type PdfLocale = (typeof VALID_PDF_LOCALES)[number];
+
+const pdf = defineCommand({
+  meta: { name: 'pdf', description: 'Render an invoice or UPO XML to a PDF (offline; requires the optional pdfmake peer)' },
+  args: {
+    file: { type: 'positional', description: 'Path to the invoice or UPO XML file', required: true },
+    template: { type: 'string', description: 'Built-in template name (e.g. fa3-default). Mutually exclusive with --template-file.' },
+    templateFile: { type: 'string', description: 'Path to a custom JSON template. Mutually exclusive with --template.' },
+    locale: { type: 'string', description: 'Label language: pl | en | pl+en (default: pl)' },
+    out: { type: 'string', description: 'Output PDF path (default: alongside the source, .pdf)' },
+    qr: { type: 'boolean', description: 'Embed the KSeF Code I QR derived from the XML' },
+    ksefNumber: { type: 'string', description: 'KSeF number to print (absent → marked OFFLINE)' },
+    upo: { type: 'boolean', description: 'Treat the input as a UPO document (otherwise auto-detected)' },
+    env: { type: 'string', description: 'Environment for the QR base URL (test/demo/prod)' },
+    json: { type: 'boolean', description: 'Output as JSON' },
+  },
+  run({ args }) {
+    return withErrorHandler(async () => {
+      const file = args.file;
+      if (!fs.existsSync(file)) {
+        throw new Error(`File not found: ${file}`);
+      }
+      if (args.template && args.templateFile) {
+        throw new Error('--template and --template-file are mutually exclusive; pass only one.');
+      }
+
+      const locale = (args.locale as string | undefined) ?? 'pl';
+      if (!VALID_PDF_LOCALES.includes(locale as PdfLocale)) {
+        throw new Error(`Invalid --locale "${locale}". Valid: ${VALID_PDF_LOCALES.join(', ')}`);
+      }
+
+      const env = args.env as 'prod' | 'test' | 'demo' | undefined;
+      const renderOpts = {
+        locale: locale as PdfLocale,
+        qr: Boolean(args.qr),
+        ...(args.ksefNumber ? { ksefNumber: args.ksefNumber as string } : {}),
+        ...(env ? { env } : {}),
+      };
+
+      // Exact bytes preserve the QR hash; pass the raw file as a Uint8Array.
+      const xmlBytes = new Uint8Array(fs.readFileSync(file));
+      const xmlStr = Buffer.from(xmlBytes).toString('utf-8');
+
+      // Lazy bridge into the internal PDF module; it lazily requires pdfmake and,
+      // when absent/incompatible, throws a friendly install hint we surface here.
+      const pdfModule = await import('../../pdf/index.js');
+
+      let bytes: Uint8Array;
+      const isUpo = Boolean(args.upo) || (pdfModule.detectInvoiceVersion(xmlStr) === null && pdfModule.detectUpoVersion(xmlStr) !== null);
+      if (isUpo) {
+        bytes = await pdfModule.renderUpoPdf(xmlBytes, renderOpts);
+      } else if (args.templateFile) {
+        bytes = await pdfModule.renderInvoicePdfFromFile(xmlBytes, args.templateFile as string, renderOpts);
+      } else if (args.template) {
+        bytes = await pdfModule.renderInvoicePdf(xmlBytes, args.template as string, renderOpts);
+      } else {
+        const version = pdfModule.detectInvoiceVersion(xmlStr);
+        const builtin = version === 'FA(2)' ? 'fa2-default' : 'fa3-default';
+        bytes = await pdfModule.renderInvoicePdf(xmlBytes, builtin, renderOpts);
+      }
+
+      const outPath = (args.out as string | undefined) ?? file.replace(/\.xml$/i, '') + '.pdf';
+      fs.writeFileSync(outPath, bytes);
+
+      if (args.json) {
+        outputResult({ file, out: outPath, bytes: bytes.length }, { json: true });
+      } else {
+        outputSuccess(`PDF written to ${outPath} (${bytes.length} bytes)`);
+      }
+    }, { json: Boolean(args.json) });
+  },
+});
+
 export const invoiceCommand = defineCommand({
   meta: { name: 'invoice', description: 'Invoice commands' },
-  subCommands: { send, build: invoiceBuild, get, query, validate: validateCmd, export: exportCmd, 'export-status': exportStatus, 'export-incremental': exportIncremental },
+  subCommands: { send, build: invoiceBuild, get, query, pdf, validate: validateCmd, export: exportCmd, 'export-status': exportStatus, 'export-incremental': exportIncremental },
 });
diff --git a/packages/ksef-client-ts/src/pdf/accessor.ts b/packages/ksef-client-ts/src/pdf/accessor.ts
new file mode 100644
index 0000000..b4d5641
--- /dev/null
+++ b/packages/ksef-client-ts/src/pdf/accessor.ts
@@ -0,0 +1,97 @@
+/**
+ * Accessor layer over `fast-xml-parser` compact output.
+ *
+ * Compact parsing (`preserveOrder: false`) is convenient for layout but leaves
+ * artifacts: single-element collections collapse from an array into an object,
+ * elements with mixed content expose their text under `#text`, and attributes
+ * are prefixed (we configure `@`). Templates never touch the parsed object
+ * directly — every binding goes through these helpers so a one-line invoice is
+ * handled exactly like a many-line one and a missing optional field never throws
+ * (unless strict mode asks it to).
+ *
+ * A path is a dot-separated walk over the parsed object, e.g.
+ * `Podmiot1.DaneIdentyfikacyjne.NIP`. A segment beginning with `@` reads an
+ * attribute, e.g. `Naglowek.KodFormularza.@kodSystemowy`.
+ */
+
+const TEXT_KEY = '#text';
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Walk `path` and return the raw node found there (object, array, or scalar),
+ * or `undefined` if any intermediate segment is absent. When descent hits an
+ * array mid-path (a collapsed/expanded repeater), the first element is followed
+ * — use {@link list} when you need every element.
+ */
+export function getNode(root: unknown, path: string): unknown {
+  const segments = path.split('.').filter((s) => s.length > 0);
+  let cur: unknown = root;
+  for (const seg of segments) {
+    if (Array.isArray(cur)) cur = cur[0];
+    if (!isRecord(cur)) return undefined;
+    cur = cur[seg];
+    if (cur === undefined) return undefined;
+  }
+  return cur;
+}
+
+function coerceScalar(node: unknown): string | undefined {
+  if (node === undefined || node === null) return undefined;
+  if (typeof node === 'string') return node;
+  if (typeof node === 'number' || typeof node === 'boolean') return String(node);
+  if (Array.isArray(node)) return coerceScalar(node[0]);
+  if (isRecord(node)) {
+    if (TEXT_KEY in node) return coerceScalar(node[TEXT_KEY]);
+    return undefined; // element with only children/attributes has no scalar value
+  }
+  return undefined;
+}
+
+/**
+ * Read a scalar binding as a string. Missing/childless nodes yield `''` by
+ * default; when `strict` is set, a missing binding throws instead — useful for
+ * catching dot-path typos in built-in templates.
+ *
+ * Handles `#text` unwrapping (mixed content) and `@attr` segments transparently.
+ */
+export function get(root: unknown, path: string, strict = false): string {
+  const scalar = coerceScalar(getNode(root, path));
+  if (scalar === undefined) {
+    if (strict) throw new Error(`Missing binding: "${path}"`);
+    return '';
+  }
+  return scalar;
+}
+
+/**
+ * Always-array read for repeaters. A single-element collection that the parser
+ * collapsed into an object is returned as a one-element array, so a repeater
+ * over `Fa.FaWiersz` iterates identically for one line or many.
+ */
+export function list(root: unknown, path: string): unknown[] {
+  const node = getNode(root, path);
+  if (node === undefined || node === null) return [];
+  return Array.isArray(node) ? node : [node];
+}
+
+/**
+ * Presence test for `when` conditions. An empty string, empty array, or missing
+ * node is falsy; a present object/number/non-empty string is truthy.
+ */
+export function has(root: unknown, path: string): boolean {
+  const node = getNode(root, path);
+  if (node === undefined || node === null) return false;
+  if (typeof node === 'string') return node.length > 0;
+  if (Array.isArray(node)) return node.length > 0;
+  if (isRecord(node)) {
+    // An element that carries only an empty `#text` is not meaningfully present.
+    if (TEXT_KEY in node && Object.keys(node).length === 1) {
+      return coerceScalar(node) !== undefined && coerceScalar(node) !== '';
+    }
+    return true;
+  }
+  return true; // number / boolean
+}
diff --git a/packages/ksef-client-ts/src/pdf/errors.ts b/packages/ksef-client-ts/src/pdf/errors.ts
new file mode 100644
index 0000000..b8b9eba
--- /dev/null
+++ b/packages/ksef-client-ts/src/pdf/errors.ts
@@ -0,0 +1,13 @@
+import { KSeFError } from '../errors/ksef-error.js';
+
+/**
+ * PDF-module runtime error: missing/incompatible `pdfmake`, template/version
+ * mismatch, or nesting-depth overflow. Structural DSL validation failures use
+ * {@link KSeFValidationError} from core instead.
+ */
+export class KSeFPdfError extends KSeFError {
+  constructor(message: string) {
+    super(message);
+    this.name = 'KSeFPdfError';
+  }
+}
diff --git a/packages/ksef-client-ts/src/pdf/fonts.ts b/packages/ksef-client-ts/src/pdf/fonts.ts
new file mode 100644
index 0000000..c00f5a6
--- /dev/null
+++ b/packages/ksef-client-ts/src/pdf/fonts.ts
@@ -0,0 +1,110 @@
+/**
+ * Lazy `pdfmake` acquisition. `pdfmake` is an optional peer, so this is called
+ * only from a render path — never at module load — which keeps `./pdf` a "cold"
+ * import (see the subpath contract). On absence or an incompatible version we
+ * throw a friendly, actionable error instead of a raw resolver crash.
+ *
+ * The version guard checks `^0.2.20` (`>=0.2.20 <0.3.0`) by semver, not by
+ * feature-detection: the spike showed 0.3.x can pass shallow shape checks yet
+ * hang in `getBuffer`, so only the version number is trustworthy.
+ */
+import { createRequire } from 'node:module';
+import { KSeFPdfError } from './errors.js';
+
+const REQUIRED_RANGE = '^0.2.20';
+const INSTALL_HINT = `npm i "pdfmake@${REQUIRED_RANGE}"`;
+
+/** Minimal structural view of the pdfmake browser build we depend on. */
+export interface PdfMakeLike {
+  createPdf(docDefinition: unknown): { getBuffer(cb: (buffer: Uint8Array) => void): void };
+  vfs?: unknown;
+}
+
+function missingError(): KSeFPdfError {
+  return new KSeFPdfError(
+    `PDF rendering requires the optional peer dependency "pdfmake" (${REQUIRED_RANGE}), ` +
+      `which is not installed. Install it with: ${INSTALL_HINT}`,
+  );
+}
+
+/** True iff `version` satisfies `^0.2.20` — i.e. `0.2.x` with `x >= 20`. */
+export function satisfiesRequiredRange(version: string): boolean {
+  const m = /^(\d+)\.(\d+)\.(\d+)/.exec(version.trim());
+  if (!m) return false;
+  const major = Number(m[1]);
+  const minor = Number(m[2]);
+  const patch = Number(m[3]);
+  return major === 0 && minor === 2 && patch >= 20;
+}
+
+function readPdfmakeVersion(): string | null {
+  try {
+    const require = createRequire(import.meta.url);
+    const pkg = require('pdfmake/package.json') as { version?: string };
+    return typeof pkg.version === 'string' ? pkg.version : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Assert the resolved pdfmake version is supported. `null` (not installed) →
+ * friendly install error; a version outside `^0.2.20` (e.g. 0.3.x) → a clear
+ * incompatible-version error. Extracted so it is unit-testable without a
+ * live install.
+ */
+export function assertPdfmakeVersion(version: string | null): void {
+  if (version === null) throw missingError();
+  if (!satisfiesRequiredRange(version)) {
+    throw new KSeFPdfError(
+      `PDF rendering requires pdfmake ${REQUIRED_RANGE}, but found ${version}. ` +
+        `pdfmake 0.3.x is not supported yet (incompatible import/VFS shape). Install: ${INSTALL_HINT}`,
+    );
+  }
+}
+
+/** Normalize the `vfs_fonts` module across shapes into the font map to assign. */
+export function normalizeVfs(mod: unknown): unknown {
+  const m = mod as { default?: unknown; vfs?: unknown; pdfMake?: { vfs?: unknown } } | undefined;
+  const cand = (m && 'default' in m ? m.default : m) as
+    | { vfs?: unknown; pdfMake?: { vfs?: unknown } }
+    | undefined;
+  if (cand && typeof cand === 'object') {
+    if ('vfs' in cand && cand.vfs) return cand.vfs;
+    if (cand.pdfMake && cand.pdfMake.vfs) return cand.pdfMake.vfs;
+  }
+  return cand;
+}
+
+/**
+ * Resolve, version-check, and initialize pdfmake with the bundled Roboto VFS.
+ * Throws {@link KSeFPdfError} if pdfmake is absent or outside `^0.2.20`.
+ */
+export async function loadPdfMake(): Promise<PdfMakeLike> {
+  assertPdfmakeVersion(readPdfmakeVersion());
+
+  let pdfmakeMod: unknown;
+  let vfsMod: unknown;
+  try {
+    pdfmakeMod = await import('pdfmake/build/pdfmake.js');
+    vfsMod = await import('pdfmake/build/vfs_fonts.js');
+  } catch {
+    throw missingError();
+  }
+
+  const namespace = pdfmakeMod as { default?: PdfMakeLike };
+  const pdfMake = (namespace.default ?? (pdfmakeMod as PdfMakeLike));
+  pdfMake.vfs = normalizeVfs(vfsMod);
+  return pdfMake;
+}
+
+/** Render a pdfmake document definition to PDF bytes. */
+export function createPdfBuffer(pdfMake: PdfMakeLike, docDefinition: unknown): Promise<Uint8Array> {
+  return new Promise<Uint8Array>((resolve, reject) => {
+    try {
+      pdfMake.createPdf(docDefinition).getBuffer((buffer) => resolve(Uint8Array.from(buffer)));
+    } catch (err) {
+      reject(err instanceof Error ? err : new KSeFPdfError(String(err)));
+    }
+  });
+}
diff --git a/packages/ksef-client-ts/src/pdf/format.ts b/packages/ksef-client-ts/src/pdf/format.ts
new file mode 100644
index 0000000..f27a095
--- /dev/null
+++ b/packages/ksef-client-ts/src/pdf/format.ts
@@ -0,0 +1,62 @@
+/**
+ * Value formatters referenced by DSL bindings (`format: 'money' | 'date' |
+ * 'number' | 'nip'`). Each is total: on unparseable input it returns the raw
+ * string unchanged, so a formatter never throws mid-render.
+ */
+export type FormatterName = 'money' | 'date' | 'number' | 'nip';
+
+const NBSP = ' ';
+
+function groupThousands(intPart: string): string {
+  return intPart.replace(/\B(?=(\d{3})+(?!\d))/g, NBSP);
+}
+
+/** `"1234.5"` → `"1 234,50"` (Polish monetary style, 2 decimals). */
+export function formatMoney(raw: string): string {
+  const n = Number(raw);
+  if (raw.trim() === '' || Number.isNaN(n)) return raw;
+  const fixed = Math.abs(n).toFixed(2);
+  const dot = fixed.indexOf('.');
+  const intPart = fixed.slice(0, dot);
+  const frac = fixed.slice(dot + 1);
+  const sign = n < 0 ? '-' : '';
+  return `${sign}${groupThousands(intPart)},${frac}`;
+}
+
+/** `"1234.5"` → `"1 234,5"` (grouped, no forced decimals). */
+export function formatNumber(raw: string): string {
+  const n = Number(raw);
+  if (raw.trim() === '' || Number.isNaN(n)) return raw;
+  const [intPart, frac] = Math.abs(n).toString().split('.');
+  const sign = n < 0 ? '-' : '';
+  const grouped = groupThousands(intPart ?? '0');
+  return frac ? `${sign}${grouped},${frac}` : `${sign}${grouped}`;
+}
+
+/** ISO `"2025-01-15"` (or a datetime) → `"15.01.2025"`; other inputs pass through. */
+export function formatDate(raw: string): string {
+  const m = /^(\d{4})-(\d{2})-(\d{2})/.exec(raw.trim());
+  if (!m) return raw;
+  return `${m[3]}.${m[2]}.${m[1]}`;
+}
+
+/** `"5213003700"` → `"521-300-37-00"`; non-10-digit inputs pass through. */
+export function formatNip(raw: string): string {
+  const digits = raw.replace(/\D/g, '');
+  if (digits.length !== 10) return raw;
+  return `${digits.slice(0, 3)}-${digits.slice(3, 6)}-${digits.slice(6, 8)}-${digits.slice(8, 10)}`;
+}
+
+const FORMATTERS: Record<FormatterName, (raw: string) => string> = {
+  money: formatMoney,
+  date: formatDate,
+  number: formatNumber,
+  nip: formatNip,
+};
+
+/** Apply a named formatter; an unknown name returns the value unchanged. */
+export function applyFormat(value: string, format: FormatterName | undefined): string {
+  if (!format) return value;
+  const fn = FORMATTERS[format];
+  return fn ? fn(value) : value;
+}
diff --git a/packages/ksef-client-ts/src/pdf/i18n/en.ts b/packages/ksef-client-ts/src/pdf/i18n/en.ts
new file mode 100644
index 0000000..15cf318
--- /dev/null
+++ b/packages/ksef-client-ts/src/pdf/i18n/en.ts
@@ -0,0 +1,37 @@
+import type { LabelBundle } from './types.js';
+
+/** English label bundle (mirrors the Polish key set). */
+export const en: LabelBundle = {
+  invoice: 'Invoice',
+  duplicate: 'Duplicate',
+  seller: 'Seller',
+  buyer: 'Buyer',
+  issueDate: 'Issue date',
+  invoiceNumber: 'Invoice number',
+  ksefNumber: 'KSeF number',
+  offline: 'OFFLINE',
+  lp: 'No.',
+  name: 'Name',
+  unit: 'Unit',
+  qty: 'Qty',
+  unitPrice: 'Net price',
+  vatRate: 'VAT rate',
+  net: 'Net amount',
+  vat: 'VAT amount',
+  gross: 'Gross amount',
+  totalNet: 'Total net',
+  totalVat: 'Total VAT',
+  totalDue: 'Amount due',
+  payment: 'Payment',
+  paid: 'Paid',
+  paymentDate: 'Payment due',
+  paymentMethod: 'Payment method',
+  annotations: 'Annotations',
+  upoTitle: 'Official Receipt Confirmation (UPO)',
+  ksefDocNumber: 'KSeF document number',
+  sessionRef: 'Session reference number',
+  receiptDate: 'KSeF number assignment date',
+  documentHash: 'Document hash',
+  page: 'Page',
+  of: 'of',
+};
diff --git a/packages/ksef-client-ts/src/pdf/i18n/index.ts b/packages/ksef-client-ts/src/pdf/i18n/index.ts
new file mode 100644
index 0000000..50811e7
--- /dev/null
+++ b/packages/ksef-client-ts/src/pdf/i18n/index.ts
@@ -0,0 +1,50 @@
+/**
+ * Label localization. Only `pl` and `en` bundles are maintained; `pl+en` is
+ * produced on the fly by concatenation with a configurable separator, so there
+ * is no third bundle to keep in sync. A missing key falls back to Polish, then
+ * to the key itself.
+ */
+import type { Locale, LabelBundle } from './types.js';
+import { pl } from './pl.js';
+import { en } from './en.js';
+
+export type { Locale, LabelBundle } from './types.js';
+export { pl } from './pl.js';
+export { en } from './en.js';
+
+const BUNDLES: Record<'pl' | 'en', LabelBundle> = { pl, en };
+
+export interface LabelOptions {
+  /** Separator for the `pl+en` bilingual locale. Default `' / '`. */
+  bilingualSeparator?: string;
+  /** Per-template label overrides (highest precedence). */
+  overrides?: LabelBundle;
+}
+
+function resolveOne(key: string, locale: 'pl' | 'en', overrides?: LabelBundle): string {
+  const override = overrides?.[key];
+  if (override !== undefined) return override;
+  const fromBundle = BUNDLES[locale][key];
+  if (fromBundle !== undefined) return fromBundle;
+  // Fall back to Polish, then to the raw key.
+  return pl[key] ?? key;
+}
+
+/**
+ * Resolve a label key for the given locale. For `pl+en`, resolves both and
+ * joins them with the separator (default `' / '`).
+ */
+export function resolveLabel(key: string, locale: Locale, opts: LabelOptions = {}): string {
+  if (locale === 'pl+en') {
+    const sep = opts.bilingualSeparator ?? ' / ';
+    return `${resolveOne(key, 'pl', opts.overrides)}${sep}${resolveOne(key, 'en', opts.overrides)}`;
+  }
+  return resolveOne(key, locale, opts.overrides);
+}
+
+/** A bound resolver capturing locale + options, handed to block renderers. */
+export type LabelResolver = (key: string) => string;
+
+export function makeLabelResolver(locale: Locale, opts: LabelOptions = {}): LabelResolver {
+  return (key: string) => resolveLabel(key, locale, opts);
+}
diff --git a/packages/ksef-client-ts/src/pdf/i18n/pl.ts b/packages/ksef-client-ts/src/pdf/i18n/pl.ts
new file mode 100644
index 0000000..197246f
--- /dev/null
+++ b/packages/ksef-client-ts/src/pdf/i18n/pl.ts
@@ -0,0 +1,43 @@
+import type { LabelBundle } from './types.js';
+
+/** Polish label bundle (canonical key set). */
+export const pl: LabelBundle = {
+  invoice: 'Faktura',
+  duplicate: 'Duplikat',
+  seller: 'Sprzedawca',
+  buyer: 'Nabywca',
+  issueDate: 'Data wystawienia',
+  invoiceNumber: 'Numer faktury',
+  ksefNumber: 'Numer KSeF',
+  offline: 'OFFLINE',
+  // line-item columns
+  lp: 'Lp.',
+  name: 'Nazwa',
+  unit: 'j.m.',
+  qty: 'Ilość',
+  unitPrice: 'Cena netto',
+  vatRate: 'Stawka VAT',
+  net: 'Wartość netto',
+  vat: 'Kwota VAT',
+  gross: 'Wartość brutto',
+  // totals
+  totalNet: 'Razem netto',
+  totalVat: 'Razem VAT',
+  totalDue: 'Do zapłaty',
+  // payment
+  payment: 'Płatność',
+  paid: 'Zapłacono',
+  paymentDate: 'Termin płatności',
+  paymentMethod: 'Forma płatności',
+  // annotations
+  annotations: 'Adnotacje',
+  // upo
+  upoTitle: 'Urzędowe Poświadczenie Odbioru (UPO)',
+  ksefDocNumber: 'Numer KSeF dokumentu',
+  sessionRef: 'Numer referencyjny sesji',
+  receiptDate: 'Data nadania numeru KSeF',
+  documentHash: 'Skrót dokumentu',
+  // footer
+  page: 'Strona',
+  of: 'z',
+};
diff --git a/packages/ksef-client-ts/src/pdf/i18n/types.ts b/packages/ksef-client-ts/src/pdf/i18n/types.ts
new file mode 100644
index 0000000..aa9a0a1
--- /dev/null
+++ b/packages/ksef-client-ts/src/pdf/i18n/types.ts
@@ -0,0 +1,11 @@
+/** Label language for the rendered PDF. `pl+en` is built by concatenation. */
+export type Locale = 'pl' | 'en' | 'pl+en';
+
+/**
+ * Known label keys referenced by built-in templates. Custom templates may use
+ * additional keys via per-template overrides; unknown keys fall back to their
+ * own string. Keeping this a string-keyed record (not a closed union) lets
+ * custom templates introduce labels without a type change, while the built-in
+ * bundles below document the canonical set.
+ */
+export type LabelBundle = Record<string, string>;
diff --git a/packages/ksef-client-ts/src/pdf/index.ts b/packages/ksef-client-ts/src/pdf/index.ts
new file mode 100644
index 0000000..b7a54c2
--- /dev/null
+++ b/packages/ksef-client-ts/src/pdf/index.ts
@@ -0,0 +1,195 @@
+/**
+ * `ksef-client-ts/pdf` — node-only subpath that renders KSeF invoice/UPO XML to
+ * PDF via a template-driven block DSL. `pdfmake` is an optional peer loaded
+ * lazily; importing this module without it must not throw — only a `render*`
+ * call surfaces a friendly install error.
+ *
+ * This is the public surface: its types operate on our own DSL types and
+ * `Uint8Array`, never on `@types/pdfmake`, so consumers without pdfmake still
+ * type-check `./pdf`.
+ */
+import { readFile } from 'node:fs/promises';
+import {
+  detectInvoiceVersion,
+  detectUpoVersion,
+  parseXmlForPdf,
+  type InvoiceVersion,
+  type UpoVersion,
+} from './parse.js';
+import { KSeFPdfError } from './errors.js';
+import { makeLabelResolver } from './i18n/index.js';
+import type { Locale } from './i18n/types.js';
+import { validateTemplate, type InvoiceTemplate, type TemplateSchemaId } from './template/dsl.js';
+import { interpretTemplate, type RenderContext } from './template/interpret.js';
+import { blockRegistry } from './template/blocks/index.js';
+import { getBuiltinTemplate, builtinTemplateNames } from './template/builtin/index.js';
+import { loadPdfMake, createPdfBuffer } from './fonts.js';
+import { deriveInvoiceQrUrl } from './qr.js';
+
+export type { Locale } from './i18n/types.js';
+export type { InvoiceTemplate } from './template/dsl.js';
+export { detectInvoiceVersion, detectUpoVersion } from './parse.js';
+
+export interface RenderOptions {
+  /** Label language. Default `'pl'`. */
+  locale?: Locale;
+  /** KSeF number printed on the visualization; absent → marked OFFLINE. */
+  ksefNumber?: string;
+  /** Embed the KSeF Code I QR derived from the invoice XML. */
+  qr?: boolean;
+  /** Environment used to derive the QR base URL. Default `'prod'`. */
+  env?: 'prod' | 'test' | 'demo';
+  /** Override the QR base URL (offline / non-standard). */
+  baseQrUrl?: string;
+  /** Logo as a `data:` URI. */
+  logo?: string;
+  /** Theming (accent colour only; the font is the bundled Roboto). */
+  theme?: { accent?: string };
+  /** Separator for the `pl+en` locale. Default `' / '`. */
+  bilingualSeparator?: string;
+  /** Throw on a missing binding instead of rendering an empty string. */
+  strict?: boolean;
+  /** Precomputed canonical invoice hash (base64) — used verbatim for the QR. */
+  invoiceHash?: string;
+}
+
+type RawXml = string | Uint8Array;
+
+function toXmlString(input: RawXml): string {
+  return typeof input === 'string' ? input : new TextDecoder('utf-8').decode(input);
+}
+
+/**
+ * Bindings are written relative to the document body (`Fa.P_2`, `Podmiot1.…`,
+ * or UPO `Dokument.…`), so the context root is the body element, not the parsed
+ * document wrapper.
+ */
+function extractBody(parsed: Record<string, unknown>, schema: TemplateSchemaId): unknown {
+  const key = schema.startsWith('UPO') ? 'Potwierdzenie' : 'Faktura';
+  const body = parsed[key];
+  return body && typeof body === 'object' ? body : parsed;
+}
+
+function buildContext(
+  root: unknown,
+  template: InvoiceTemplate,
+  opts: RenderOptions,
+  qrUrl: string,
+): RenderContext {
+  const label = makeLabelResolver(opts.locale ?? 'pl', {
+    bilingualSeparator: opts.bilingualSeparator,
+    overrides: template.labels,
+  });
+
+  const bindings: Record<string, string> = {
+    'opts.logo': opts.logo ?? '',
+    'opts.ksefNumber': opts.ksefNumber ?? '',
+    'opts.accent': opts.theme?.accent ?? '',
+    qrUrl,
+  };
+
+  const flags: Record<string, boolean> = {
+    hasKsefNumber: Boolean(opts.ksefNumber),
+    offline: !opts.ksefNumber,
+    qr: Boolean(opts.qr) && qrUrl !== '',
+  };
+
+  return { root, strict: opts.strict ?? false, label, bindings, flags };
+}
+
+function assertVersionMatch(xml: string, schema: TemplateSchemaId): void {
+  const detected: InvoiceVersion | UpoVersion | null = schema.startsWith('UPO')
+    ? detectUpoVersion(xml)
+    : detectInvoiceVersion(xml);
+  if (detected !== null && detected !== schema) {
+    throw new KSeFPdfError(
+      `Template targets ${schema}, but the document was detected as ${detected}. ` +
+        `Use a ${detected} template (or the matching built-in).`,
+    );
+  }
+}
+
+async function renderWithTemplate(
+  rawInput: RawXml,
+  template: InvoiceTemplate,
+  opts: RenderOptions,
+): Promise<Uint8Array> {
+  const xml = toXmlString(rawInput);
+  assertVersionMatch(xml, template.schema);
+  const parsed = parseXmlForPdf(xml);
+  const body = extractBody(parsed, template.schema);
+
+  // QR (Code I) is derived only for invoices — the hash is computed over the
+  // ORIGINAL input bytes (bypassing the parser) so it matches the KSeF registry.
+  let qrUrl = '';
+  if (opts.qr && !template.schema.startsWith('UPO')) {
+    qrUrl = deriveInvoiceQrUrl({
+      rawInput,
+      body,
+      env: opts.env,
+      baseQrUrl: opts.baseQrUrl,
+      invoiceHash: opts.invoiceHash,
+      strict: opts.strict,
+    });
+  }
+
+  const ctx = buildContext(body, template, opts, qrUrl);
+  const doc = interpretTemplate(template, ctx, blockRegistry);
+  const pdfMake = await loadPdfMake();
+  return createPdfBuffer(pdfMake, doc);
+}
+
+/** Render an invoice using a built-in template selected by name. */
+export async function renderInvoicePdf(
+  xml: RawXml,
+  name: string,
+  opts: RenderOptions = {},
+): Promise<Uint8Array> {
+  const template = getBuiltinTemplate(name);
+  if (!template) {
+    throw new KSeFPdfError(
+      `Unknown built-in template "${name}". Available: ${builtinTemplateNames().join(', ')}`,
+    );
+  }
+  return renderWithTemplate(xml, template, opts);
+}
+
+/** Render an invoice using a custom template loaded from a JSON file. */
+export async function renderInvoicePdfFromFile(
+  xml: RawXml,
+  path: string,
+  opts: RenderOptions = {},
+): Promise<Uint8Array> {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(await readFile(path, 'utf-8'));
+  } catch (err) {
+    throw new KSeFPdfError(`Failed to read template file "${path}": ${(err as Error).message}`);
+  }
+  const template = validateTemplate(parsed);
+  return renderWithTemplate(xml, template, opts);
+}
+
+/** Render an invoice using a custom template object. */
+export async function renderInvoicePdfFromTemplate(
+  xml: RawXml,
+  template: InvoiceTemplate,
+  opts: RenderOptions = {},
+): Promise<Uint8Array> {
+  const validated = validateTemplate(template);
+  return renderWithTemplate(xml, validated, opts);
+}
+
+const UPO_TEMPLATE_BY_VERSION: Record<UpoVersion, string> = {
+  'UPO(4.2)': 'upo-4_2',
+  'UPO(4.3)': 'upo-4_3',
+};
+
+/** Render a UPO receipt using the matching built-in UPO template. */
+export async function renderUpoPdf(xml: RawXml, opts: RenderOptions = {}): Promise<Uint8Array> {
+  const version = detectUpoVersion(toXmlString(xml));
+  if (!version) {
+    throw new KSeFPdfError('Input is not a recognized UPO(4.2)/UPO(4.3) document.');
+  }
+  return renderInvoicePdf(xml, UPO_TEMPLATE_BY_VERSION[version], opts);
+}
diff --git a/packages/ksef-client-ts/src/pdf/parse.ts b/packages/ksef-client-ts/src/pdf/parse.ts
new file mode 100644
index 0000000..75031f4
--- /dev/null
+++ b/packages/ksef-client-ts/src/pdf/parse.ts
@@ -0,0 +1,66 @@
+/**
+ * Compact XML parsing + version detection for the PDF renderer.
+ *
+ * Uses `fast-xml-parser` in compact mode (`preserveOrder: false`) — unlike the
+ * core `parseXml` (which preserves order and is awkward for layout). Numbers are
+ * kept as strings (`parseTagValue: false`) so monetary precision and leading
+ * zeros survive; formatters own number presentation. Namespace prefixes are
+ * stripped so paths stay clean (`Fa.P_2`, not `tns:Fa.tns:P_2`). Attributes are
+ * exposed under the `@` prefix and read through the accessor layer.
+ */
+import { XMLParser } from 'fast-xml-parser';
+import { get } from './accessor.js';
+
+export type InvoiceVersion = 'FA(2)' | 'FA(3)';
+export type UpoVersion = 'UPO(4.2)' | 'UPO(4.3)';
+
+export const pdfXmlParser = new XMLParser({
+  ignoreAttributes: false,
+  attributeNamePrefix: '@',
+  parseTagValue: false,
+  parseAttributeValue: false,
+  removeNSPrefix: true,
+  trimValues: true,
+});
+
+/**
+ * Parse KSeF invoice/UPO XML into a compact object for template binding.
+ * `fast-xml-parser` always returns an object (empty/non-XML input yields `{}`).
+ */
+export function parseXmlForPdf(xml: string): Record<string, unknown> {
+  return pdfXmlParser.parse(xml) as Record<string, unknown>;
+}
+
+/**
+ * Detect the invoice schema version. Reads the `kodSystemowy` attribute
+ * (`"FA (2)"` / `"FA (3)"`) and the `WariantFormularza` element; returns `null`
+ * for anything that is not a recognized FA(2)/FA(3) invoice. FA(1) is not
+ * supported.
+ */
+export function detectInvoiceVersion(xml: string): InvoiceVersion | null {
+  const parsed = parseXmlForPdf(xml);
+  if (!('Faktura' in parsed)) return null;
+
+  const kod = get(parsed, 'Faktura.Naglowek.KodFormularza.@kodSystemowy').replace(/\s+/g, '');
+  const variant = get(parsed, 'Faktura.Naglowek.WariantFormularza').trim();
+
+  if (kod === 'FA(3)' || variant === '3') return 'FA(3)';
+  if (kod === 'FA(2)' || variant === '2') return 'FA(2)';
+  return null;
+}
+
+/**
+ * Detect the UPO version. Requires a `Potwierdzenie` root, then reads the
+ * version from the namespace marker in the raw XML (`.../KSeF/v4-3` →
+ * `UPO(4.3)`, `v4-2` → `UPO(4.2)`). The default `xmlns` declaration is not
+ * surfaced as an attribute by the compact parser, so we scan the source
+ * directly. Returns `null` for non-UPO documents.
+ */
+export function detectUpoVersion(xml: string): UpoVersion | null {
+  const parsed = parseXmlForPdf(xml);
+  if (!('Potwierdzenie' in parsed)) return null;
+
+  if (/KSeF\/v4-3\b/.test(xml)) return 'UPO(4.3)';
+  if (/KSeF\/v4-2\b/.test(xml)) return 'UPO(4.2)';
+  return null;
+}
diff --git a/packages/ksef-client-ts/src/pdf/pdfmake-modules.d.ts b/packages/ksef-client-ts/src/pdf/pdfmake-modules.d.ts
new file mode 100644
index 0000000..a8dd5b5
--- /dev/null
+++ b/packages/ksef-client-ts/src/pdf/pdfmake-modules.d.ts
@@ -0,0 +1,11 @@
+/**
+ * Minimal ambient declarations for the two pdfmake browser-build submodules the
+ * renderer lazily imports. We deliberately do NOT depend on `@types/pdfmake`:
+ * the published DefinitelyTyped package targets the 0.3.x API (promise-based
+ * `getBuffer`), which does not match the pinned 0.2.x runtime, and it does not
+ * type these `/build/*` submodules usefully anyway. `fonts.ts` narrows the
+ * `any` import to the local `PdfMakeLike` shape, so this keeps the `./pdf`
+ * public types free of any pdfmake dependency (the "cold module" invariant).
+ */
+declare module 'pdfmake/build/pdfmake.js';
+declare module 'pdfmake/build/vfs_fonts.js';
diff --git a/packages/ksef-client-ts/src/pdf/qr.ts b/packages/ksef-client-ts/src/pdf/qr.ts
new file mode 100644
index 0000000..5d79c29
--- /dev/null
+++ b/packages/ksef-client-ts/src/pdf/qr.ts
@@ -0,0 +1,72 @@
+/**
+ * QR ("Code I") derivation for the PDF module.
+ *
+ * The whole point of this module is a byte-exact invoice hash: KSeF registers an
+ * invoice under the SHA-256 of the *exact bytes* it received. If we hashed a
+ * re-serialized DOM, a stray BOM, a CRLF↔LF swap, a re-encode, or a pretty-print
+ * would flip the digest and the QR would point at a hash absent from the
+ * registry. So the hash here is always taken over the ORIGINAL INPUT BYTES,
+ * never over parsed/reserialized XML.
+ */
+import crypto from 'node:crypto';
+import { VerificationLinkService } from '../qr/verification-link-service.js';
+import { Environment } from '../config/environments.js';
+import { get } from './accessor.js';
+
+/**
+ * SHA-256 over the raw invoice bytes, returned as standard base64.
+ *
+ * A `Uint8Array` is hashed directly. A `string` is hashed as
+ * `Buffer.from(str, 'utf8')` AS-IS — no BOM strip, no re-encode, no newline
+ * normalization. The caller is responsible for handing us the same bytes KSeF
+ * received.
+ */
+export function computeInvoiceHashBase64(rawInput: string | Uint8Array): string {
+  const bytes = typeof rawInput === 'string' ? Buffer.from(rawInput, 'utf8') : rawInput;
+  return crypto.createHash('sha256').update(bytes).digest('base64');
+}
+
+/**
+ * Resolve the base QR URL. An explicit `override` always wins; otherwise the
+ * `env` selects the matching KSeF QR host, defaulting to production.
+ */
+export function resolveBaseQrUrl(
+  env: 'prod' | 'test' | 'demo' | undefined,
+  override?: string,
+): string {
+  if (override !== undefined && override !== '') return override;
+  switch (env) {
+    case 'test':
+      return Environment.TEST.qrUrl;
+    case 'demo':
+      return Environment.DEMO.qrUrl;
+    case 'prod':
+    default:
+      return Environment.PROD.qrUrl;
+  }
+}
+
+export interface DeriveInvoiceQrUrlParams {
+  /** Original invoice bytes (or the exact UTF-8 string) — hashed AS-IS. */
+  rawInput: string | Uint8Array;
+  /** Parsed document body node (`Faktura`), same shape as `RenderContext.root`. */
+  body: unknown;
+  env?: 'prod' | 'test' | 'demo';
+  baseQrUrl?: string;
+  /** Pre-computed hash; when set it is used VERBATIM (no recompute). */
+  invoiceHash?: string;
+  strict?: boolean;
+}
+
+/**
+ * Derive the invoice verification URL (Code I) from the raw bytes + parsed body.
+ * An `invoiceHash` override is used verbatim; otherwise the hash is computed over
+ * the raw input bytes.
+ */
+export function deriveInvoiceQrUrl(params: DeriveInvoiceQrUrlParams): string {
+  const nip = get(params.body, 'Podmiot1.DaneIdentyfikacyjne.NIP', params.strict);
+  const issueDate = get(params.body, 'P_1', params.strict);
+  const hash = params.invoiceHash ?? computeInvoiceHashBase64(params.rawInput);
+  const base = resolveBaseQrUrl(params.env, params.baseQrUrl);
+  return new VerificationLinkService(base).buildInvoiceVerificationUrl(nip, issueDate, hash);
+}
diff --git a/packages/ksef-client-ts/src/pdf/template/blocks/annotations.ts b/packages/ksef-client-ts/src/pdf/template/blocks/annotations.ts
new file mode 100644
index 0000000..5a1dccf
--- /dev/null
+++ b/packages/ksef-client-ts/src/pdf/template/blocks/annotations.ts
@@ -0,0 +1,23 @@
+import { applyFormat } from '../../format.js';
+import type { AnnotationsBlock } from '../dsl.js';
+import { resolveBinding, type BlockRenderer, type PdfNode } from '../interpret.js';
+
+/**
+ * Legal annotations: an `annotations` heading followed by one `label: value`
+ * line per {@link AnnotationsBlock.fields} entry (localized label + formatted
+ * scalar binding).
+ */
+export const annotationsRenderer: BlockRenderer<AnnotationsBlock> = (block, ctx) => {
+  const stack: PdfNode[] = [{ text: ctx.label('annotations'), style: 'h2' }];
+  for (const field of block.fields) {
+    stack.push({
+      text: `${ctx.label(field.label)}: ${applyFormat(resolveBinding(field.path, ctx), field.format)}`,
+    });
+  }
+
+  return {
+    stack,
+    margin: [0, 8, 0, 8],
+    ...(block.style ? { style: block.style } : {}),
+  };
+};
diff --git a/packages/ksef-client-ts/src/pdf/template/blocks/footer.ts b/packages/ksef-client-ts/src/pdf/template/blocks/footer.ts
new file mode 100644
index 0000000..727f3c7
--- /dev/null
+++ b/packages/ksef-client-ts/src/pdf/template/blocks/footer.ts
@@ -0,0 +1,16 @@
+import type { FooterBlock } from '../dsl.js';
+import { resolveText, type BlockRenderer } from '../interpret.js';
+
+/**
+ * Document footer: a single centered text node resolved from the block's
+ * `label` (i18n) or literal `text`. Rendered inline in the content flow (not via
+ * pdfmake's `docDefinition.footer` callback); the block's optional style is
+ * applied when present.
+ */
+export const footerRenderer: BlockRenderer<FooterBlock> = (block, ctx) => {
+  return {
+    text: resolveText({ label: block.label, text: block.text }, ctx),
+    alignment: 'center',
+    ...(block.style ? { style: block.style } : {}),
+  };
+};
diff --git a/packages/ksef-client-ts/src/pdf/template/blocks/header.ts b/packages/ksef-client-ts/src/pdf/template/blocks/header.ts
new file mode 100644
index 0000000..1b8b3b1
--- /dev/null
+++ b/packages/ksef-client-ts/src/pdf/template/blocks/header.ts
@@ -0,0 +1,33 @@
+import { applyFormat } from '../../format.js';
+import type { HeaderBlock } from '../dsl.js';
+import { resolveBinding, resolveText, type BlockRenderer, type PdfNode } from '../interpret.js';
+
+/**
+ * Invoice header: optional logo, a title (defaults to the localized "Invoice"
+ * label), and the invoice number/date stacked on the right.
+ */
+export const headerRenderer: BlockRenderer<HeaderBlock> = (block, ctx) => {
+  const left: PdfNode[] = [];
+  if (block.logo) {
+    const logo = resolveBinding(block.logo, ctx);
+    if (logo) left.push({ image: logo, width: 120, margin: [0, 0, 0, 6] });
+  }
+  const title = resolveText(block.title, ctx) || ctx.label('invoice');
+  left.push({ text: title, style: block.style ?? 'title' });
+
+  const right: PdfNode[] = [];
+  if (block.number) {
+    right.push({ text: `${ctx.label('invoiceNumber')}: ${resolveBinding(block.number, ctx)}` });
+  }
+  if (block.date) {
+    right.push({ text: `${ctx.label('issueDate')}: ${applyFormat(resolveBinding(block.date, ctx), 'date')}` });
+  }
+
+  return {
+    columns: [
+      { width: '*', stack: left },
+      { width: 'auto', stack: right, alignment: 'right' },
+    ],
+    margin: [0, 0, 0, 12],
+  };
+};
diff --git a/packages/ksef-client-ts/src/pdf/template/blocks/image.ts b/packages/ksef-client-ts/src/pdf/template/blocks/image.ts
new file mode 100644
index 0000000..3a9caed
--- /dev/null
+++ b/packages/ksef-client-ts/src/pdf/template/blocks/image.ts
@@ -0,0 +1,14 @@
+import type { ImageBlock } from '../dsl.js';
+import { resolveBinding, type BlockRenderer } from '../interpret.js';
+
+/**
+ * Renders an image. The source is either a literal `data:` URI (`src`) or a
+ * binding (`path`) resolved against the document root — `src` wins when both are
+ * present. An empty/absent source yields an empty text node rather than throwing,
+ * so an optional logo simply disappears. Never touches the filesystem.
+ */
+export const imageRenderer: BlockRenderer<ImageBlock> = (block, ctx) => {
+  const src = block.src ?? (block.path !== undefined ? resolveBinding(block.path, ctx) : '');
+  if (!src) return { text: '' };
+  return { image: src, width: block.width ?? 120 };
+};
diff --git a/packages/ksef-client-ts/src/pdf/template/blocks/index.ts b/packages/ksef-client-ts/src/pdf/template/blocks/index.ts
new file mode 100644
index 0000000..e89782a
--- /dev/null
+++ b/packages/ksef-client-ts/src/pdf/template/blocks/index.ts
@@ -0,0 +1,31 @@
+/**
+ * Block-renderer registry. Each renderer lives in its own module and is
+ * aggregated here; the interpreter merges this over its core primitives
+ * (`text`/`stack`/`columns`/`divider`/`spacer`). Renderers are authored against
+ * their narrow block type, so the narrowing cast at registration is sound (the
+ * interpreter keys them by discriminant).
+ */
+import type { BlockRegistry, BlockRenderer } from '../interpret.js';
+import { headerRenderer } from './header.js';
+import { partiesRenderer } from './parties.js';
+import { linesRenderer } from './lines.js';
+import { totalsRenderer } from './totals.js';
+import { paymentRenderer } from './payment.js';
+import { annotationsRenderer } from './annotations.js';
+import { footerRenderer } from './footer.js';
+import { tableRenderer } from './table.js';
+import { imageRenderer } from './image.js';
+import { qrRenderer } from './qr.js';
+
+export const blockRegistry: BlockRegistry = {
+  header: headerRenderer as BlockRenderer,
+  parties: partiesRenderer as BlockRenderer,
+  lines: linesRenderer as BlockRenderer,
+  totals: totalsRenderer as BlockRenderer,
+  payment: paymentRenderer as BlockRenderer,
+  annotations: annotationsRenderer as BlockRenderer,
+  footer: footerRenderer as BlockRenderer,
+  table: tableRenderer as BlockRenderer,
+  image: imageRenderer as BlockRenderer,
+  qr: qrRenderer as BlockRenderer,
+};
diff --git a/packages/ksef-client-ts/src/pdf/template/blocks/lines.ts b/packages/ksef-client-ts/src/pdf/template/blocks/lines.ts
new file mode 100644
index 0000000..2e30ea8
--- /dev/null
+++ b/packages/ksef-client-ts/src/pdf/template/blocks/lines.ts
@@ -0,0 +1,30 @@
+import { applyFormat } from '../../format.js';
+import { get, list } from '../../accessor.js';
+import type { LinesBlock } from '../dsl.js';
+import { type BlockRenderer, type PdfNode } from '../interpret.js';
+
+/**
+ * Invoice line items as a pdfmake `table`. The header row echoes each column's
+ * localized label (bold); the body has one row per repeater entry read from
+ * {@link LinesBlock.from} via {@link list} (a single collapsed line is
+ * normalized to a one-element array, so one line renders like many). Each cell
+ * reads its column path row-relative with {@link get} and applies the column's
+ * formatter. With no entries only the header row is emitted.
+ */
+export const linesRenderer: BlockRenderer<LinesBlock> = (block, ctx) => {
+  const headerRow: PdfNode[] = block.columns.map((c) => ({ text: ctx.label(c.label), bold: true }));
+  const bodyRows: PdfNode[][] = list(ctx.root, block.from).map((row) =>
+    block.columns.map((c) => ({ text: applyFormat(get(row, c.path, ctx.strict), c.format) })),
+  );
+
+  return {
+    table: {
+      headerRows: 1,
+      widths: block.columns.map(() => '*'),
+      body: [headerRow, ...bodyRows],
+    },
+    layout: 'lightHorizontalLines',
+    margin: [0, 0, 0, 12],
+    ...(block.style ? { style: block.style } : {}),
+  };
+};
diff --git a/packages/ksef-client-ts/src/pdf/template/blocks/parties.ts b/packages/ksef-client-ts/src/pdf/template/blocks/parties.ts
new file mode 100644
index 0000000..d19a6d6
--- /dev/null
+++ b/packages/ksef-client-ts/src/pdf/template/blocks/parties.ts
@@ -0,0 +1,22 @@
+import type { PartiesBlock, PartyColumn } from '../dsl.js';
+import { resolveBinding, type BlockRenderer, type PdfNode } from '../interpret.js';
+
+/**
+ * Seller/buyer parties: a two-column layout. Each side is a stack led by a bold
+ * label line (`ctx.label(side.label)`, styled `h2`) followed by one text line
+ * per binding path in `side.fields`. Left = {@link PartiesBlock.left}, right =
+ * {@link PartiesBlock.right}.
+ */
+export const partiesRenderer: BlockRenderer<PartiesBlock> = (block, ctx) => {
+  const side = (col: PartyColumn): PdfNode => {
+    const stack: PdfNode[] = [{ text: ctx.label(col.label), style: 'h2' }];
+    for (const path of col.fields) stack.push({ text: resolveBinding(path, ctx) });
+    return { width: '*', stack };
+  };
+
+  return {
+    columns: [side(block.left), side(block.right)],
+    margin: [0, 0, 0, 12],
+    ...(block.style ? { style: block.style } : {}),
+  };
+};
diff --git a/packages/ksef-client-ts/src/pdf/template/blocks/payment.ts b/packages/ksef-client-ts/src/pdf/template/blocks/payment.ts
new file mode 100644
index 0000000..e5bf859
--- /dev/null
+++ b/packages/ksef-client-ts/src/pdf/template/blocks/payment.ts
@@ -0,0 +1,24 @@
+import { applyFormat } from '../../format.js';
+import type { PaymentBlock } from '../dsl.js';
+import { resolveBinding, type BlockRenderer, type PdfNode } from '../interpret.js';
+
+/**
+ * Payment details: a `payment` heading followed by one `label: value` line per
+ * {@link PaymentBlock.rows} entry (localized label + formatted scalar binding).
+ * Visibility (`when`) is resolved centrally by the interpreter, so this renderer
+ * always emits its content.
+ */
+export const paymentRenderer: BlockRenderer<PaymentBlock> = (block, ctx) => {
+  const stack: PdfNode[] = [{ text: ctx.label('payment'), style: 'h2' }];
+  for (const row of block.rows) {
+    stack.push({
+      text: `${ctx.label(row.label)}: ${applyFormat(resolveBinding(row.path, ctx), row.format)}`,
+    });
+  }
+
+  return {
+    stack,
+    margin: [0, 8, 0, 8],
+    ...(block.style ? { style: block.style } : {}),
+  };
+};
diff --git a/packages/ksef-client-ts/src/pdf/template/blocks/qr.ts b/packages/ksef-client-ts/src/pdf/template/blocks/qr.ts
new file mode 100644
index 0000000..d437d4c
--- /dev/null
+++ b/packages/ksef-client-ts/src/pdf/template/blocks/qr.ts
@@ -0,0 +1,14 @@
+import type { QrBlock } from '../dsl.js';
+import type { BlockRenderer } from '../interpret.js';
+
+/**
+ * Renders the invoice verification QR ("Code I"). The URL is derived by the
+ * orchestrator and injected as the `qrUrl` binding — an empty binding (no
+ * derivable hash/NIP/date) collapses to an empty text node rather than emitting
+ * a broken code. `when` is handled centrally by the interpreter.
+ */
+export const qrRenderer: BlockRenderer<QrBlock> = (block, ctx) => {
+  const url = ctx.bindings['qrUrl'] ?? '';
+  if (!url) return { text: '' };
+  return { qr: url, fit: block.fit ?? 100 };
+};
diff --git a/packages/ksef-client-ts/src/pdf/template/blocks/table.ts b/packages/ksef-client-ts/src/pdf/template/blocks/table.ts
new file mode 100644
index 0000000..a4b239b
--- /dev/null
+++ b/packages/ksef-client-ts/src/pdf/template/blocks/table.ts
@@ -0,0 +1,45 @@
+import { get, list } from '../../accessor.js';
+import { applyFormat } from '../../format.js';
+import type { TableBlock } from '../dsl.js';
+import { resolveBinding, type BlockRenderer, type PdfNode } from '../interpret.js';
+
+/**
+ * Generic pdfmake `table`. Two modes:
+ *
+ * - **Repeater** (`from` set): body rows come from `list(root, from)` — always an
+ *   array, so a single collapsed row iterates like many — and each cell reads a
+ *   row-relative binding via `get(row, col.path)`.
+ * - **Single row** (`from` absent): one body row read against the document root
+ *   via `resolveBinding(col.path)`.
+ *
+ * A header row of localized `col.label`s is prepended unless `headers` is
+ * explicitly `false`. Columns share the width evenly (`'*'`) under a light
+ * horizontal-line layout.
+ */
+export const tableRenderer: BlockRenderer<TableBlock> = (block, ctx) => {
+  const { columns } = block;
+  const showHeaders = block.headers !== false;
+  const body: PdfNode[][] = [];
+
+  if (showHeaders) {
+    body.push(columns.map((col) => ({ text: ctx.label(col.label), bold: true })));
+  }
+
+  if (block.from !== undefined) {
+    for (const row of list(ctx.root, block.from)) {
+      body.push(columns.map((col) => ({ text: applyFormat(get(row, col.path, ctx.strict), col.format) })));
+    }
+  } else {
+    body.push(columns.map((col) => ({ text: applyFormat(resolveBinding(col.path, ctx), col.format) })));
+  }
+
+  const node: Record<string, unknown> = {
+    table: {
+      headerRows: showHeaders ? 1 : 0,
+      widths: columns.map(() => '*'),
+      body,
+    },
+    layout: 'lightHorizontalLines',
+  };
+  return block.style ? { ...node, style: block.style } : node;
+};
diff --git a/packages/ksef-client-ts/src/pdf/template/blocks/totals.ts b/packages/ksef-client-ts/src/pdf/template/blocks/totals.ts
new file mode 100644
index 0000000..8cc14eb
--- /dev/null
+++ b/packages/ksef-client-ts/src/pdf/template/blocks/totals.ts
@@ -0,0 +1,29 @@
+import { applyFormat } from '../../format.js';
+import type { TotalsBlock } from '../dsl.js';
+import { resolveBinding, type BlockRenderer, type PdfNode } from '../interpret.js';
+
+/**
+ * Totals summary: a compact, right-aligned label/value table. Each row of
+ * {@link TotalsBlock.rows} contributes a bold label (`ctx.label(row.label)`)
+ * and its formatted scalar binding. The borderless table is pushed to the right
+ * edge by an elastic spacer column.
+ */
+export const totalsRenderer: BlockRenderer<TotalsBlock> = (block, ctx) => {
+  const body: PdfNode[][] = block.rows.map((row) => [
+    { text: ctx.label(row.label), bold: true },
+    { text: applyFormat(resolveBinding(row.path, ctx), row.format), alignment: 'right' },
+  ]);
+
+  return {
+    columns: [
+      { width: '*', text: '' },
+      {
+        width: 'auto',
+        table: { widths: ['auto', 'auto'], body },
+        layout: 'noBorders',
+      },
+    ],
+    margin: [0, 4, 0, 8],
+    ...(block.style ? { style: block.style } : {}),
+  };
+};
diff --git a/packages/ksef-client-ts/src/pdf/template/builtin/fa2-default.json b/packages/ksef-client-ts/src/pdf/template/builtin/fa2-default.json
new file mode 100644
index 0000000..d58373d
--- /dev/null
+++ b/packages/ksef-client-ts/src/pdf/template/builtin/fa2-default.json
@@ -0,0 +1,81 @@
+{
+  "schema": "FA(2)",
+  "page": { "size": "A4", "margins": [40, 40, 40, 50] },
+  "styles": {
+    "title": { "fontSize": 20, "bold": true },
+    "h2": { "fontSize": 10, "bold": true, "margin": [0, 10, 0, 3], "color": "#333333" },
+    "muted": { "color": "#666666", "fontSize": 8 },
+    "offline": { "color": "#b00020", "bold": true },
+    "footerNote": { "fontSize": 7, "color": "#999999" }
+  },
+  "blocks": [
+    { "type": "header", "logo": "opts.logo", "title": { "label": "invoice" }, "number": "Fa.P_2", "date": "Fa.P_1" },
+    {
+      "type": "columns",
+      "when": "hasKsefNumber",
+      "columns": [
+        { "type": "text", "label": "ksefNumber", "style": "muted" },
+        { "type": "text", "path": "opts.ksefNumber", "style": "muted" }
+      ]
+    },
+    { "type": "text", "label": "offline", "when": "offline", "style": "offline" },
+    { "type": "divider" },
+    { "type": "spacer", "height": 6 },
+    {
+      "type": "parties",
+      "left": {
+        "label": "seller",
+        "fields": [
+          "Podmiot1.DaneIdentyfikacyjne.Nazwa",
+          "Podmiot1.DaneIdentyfikacyjne.NIP",
+          "Podmiot1.Adres.AdresL1",
+          "Podmiot1.Adres.AdresL2"
+        ]
+      },
+      "right": {
+        "label": "buyer",
+        "fields": [
+          "Podmiot2.DaneIdentyfikacyjne.Nazwa",
+          "Podmiot2.DaneIdentyfikacyjne.NIP",
+          "Podmiot2.Adres.AdresL1",
+          "Podmiot2.Adres.AdresL2"
+        ]
+      }
+    },
+    { "type": "spacer", "height": 12 },
+    {
+      "type": "lines",
+      "from": "Fa.FaWiersz",
+      "columns": [
+        { "label": "lp", "path": "NrWierszaFa" },
+        { "label": "name", "path": "P_7" },
+        { "label": "unit", "path": "P_8A" },
+        { "label": "qty", "path": "P_8B", "format": "number" },
+        { "label": "unitPrice", "path": "P_9A", "format": "money" },
+        { "label": "vatRate", "path": "P_12" },
+        { "label": "net", "path": "P_11", "format": "money" }
+      ]
+    },
+    { "type": "spacer", "height": 10 },
+    {
+      "type": "totals",
+      "rows": [
+        { "label": "totalNet", "path": "Fa.P_13_1", "format": "money" },
+        { "label": "totalVat", "path": "Fa.P_14_1", "format": "money" },
+        { "label": "totalDue", "path": "Fa.P_15", "format": "money" }
+      ]
+    },
+    { "type": "spacer", "height": 10 },
+    {
+      "type": "payment",
+      "when": "Fa.Platnosc",
+      "rows": [
+        { "label": "paid", "path": "Fa.Platnosc.Zaplacono" },
+        { "label": "paymentDate", "path": "Fa.Platnosc.DataZaplaty", "format": "date" },
+        { "label": "paymentMethod", "path": "Fa.Platnosc.FormaPlatnosci" }
+      ]
+    },
+    { "type": "qr", "when": "qr", "fit": 90 },
+    { "type": "footer", "text": "ksef-client-ts", "style": "footerNote" }
+  ]
+}
diff --git a/packages/ksef-client-ts/src/pdf/template/builtin/fa3-default.json b/packages/ksef-client-ts/src/pdf/template/builtin/fa3-default.json
new file mode 100644
index 0000000..99a93c0
--- /dev/null
+++ b/packages/ksef-client-ts/src/pdf/template/builtin/fa3-default.json
@@ -0,0 +1,81 @@
+{
+  "schema": "FA(3)",
+  "page": { "size": "A4", "margins": [40, 40, 40, 50] },
+  "styles": {
+    "title": { "fontSize": 20, "bold": true },
+    "h2": { "fontSize": 10, "bold": true, "margin": [0, 10, 0, 3], "color": "#333333" },
+    "muted": { "color": "#666666", "fontSize": 8 },
+    "offline": { "color": "#b00020", "bold": true },
+    "footerNote": { "fontSize": 7, "color": "#999999" }
+  },
+  "blocks": [
+    { "type": "header", "logo": "opts.logo", "title": { "label": "invoice" }, "number": "Fa.P_2", "date": "Fa.P_1" },
+    {
+      "type": "columns",
+      "when": "hasKsefNumber",
+      "columns": [
+        { "type": "text", "label": "ksefNumber", "style": "muted" },
+        { "type": "text", "path": "opts.ksefNumber", "style": "muted" }
+      ]
+    },
+    { "type": "text", "label": "offline", "when": "offline", "style": "offline" },
+    { "type": "divider" },
+    { "type": "spacer", "height": 6 },
+    {
+      "type": "parties",
+      "left": {
+        "label": "seller",
+        "fields": [
+          "Podmiot1.DaneIdentyfikacyjne.Nazwa",
+          "Podmiot1.DaneIdentyfikacyjne.NIP",
+          "Podmiot1.Adres.AdresL1",
+          "Podmiot1.Adres.AdresL2"
+        ]
+      },
+      "right": {
+        "label": "buyer",
+        "fields": [
+          "Podmiot2.DaneIdentyfikacyjne.Nazwa",
+          "Podmiot2.DaneIdentyfikacyjne.NIP",
+          "Podmiot2.Adres.AdresL1",
+          "Podmiot2.Adres.AdresL2"
+        ]
+      }
+    },
+    { "type": "spacer", "height": 12 },
+    {
+      "type": "lines",
+      "from": "Fa.FaWiersz",
+      "columns": [
+        { "label": "lp", "path": "NrWierszaFa" },
+        { "label": "name", "path": "P_7" },
+        { "label": "unit", "path": "P_8A" },
+        { "label": "qty", "path": "P_8B", "format": "number" },
+        { "label": "unitPrice", "path": "P_9A", "format": "money" },
+        { "label": "vatRate", "path": "P_12" },
+        { "label": "net", "path": "P_11", "format": "money" }
+      ]
+    },
+    { "type": "spacer", "height": 10 },
+    {
+      "type": "totals",
+      "rows": [
+        { "label": "totalNet", "path": "Fa.P_13_1", "format": "money" },
+        { "label": "totalVat", "path": "Fa.P_14_1", "format": "money" },
+        { "label": "totalDue", "path": "Fa.P_15", "format": "money" }
+      ]
+    },
+    { "type": "spacer", "height": 10 },
+    {
+      "type": "payment",
+      "when": "Fa.Platnosc",
+      "rows": [
+        { "label": "paid", "path": "Fa.Platnosc.Zaplacono" },
+        { "label": "paymentDate", "path": "Fa.Platnosc.DataZaplaty", "format": "date" },
+        { "label": "paymentMethod", "path": "Fa.Platnosc.FormaPlatnosci" }
+      ]
+    },
+    { "type": "qr", "when": "qr", "fit": 90 },
+    { "type": "footer", "text": "ksef-client-ts", "style": "footerNote" }
+  ]
+}
diff --git a/packages/ksef-client-ts/src/pdf/template/builtin/index.ts b/packages/ksef-client-ts/src/pdf/template/builtin/index.ts
new file mode 100644
index 0000000..8806ce9
--- /dev/null
+++ b/packages/ksef-client-ts/src/pdf/template/builtin/index.ts
@@ -0,0 +1,26 @@
+/**
+ * Built-in templates. JSON is imported (not read from disk) so tsup inlines it
+ * into the bundle — no runtime filesystem access is needed for built-ins.
+ */
+import { validateTemplate, type InvoiceTemplate } from '../dsl.js';
+import fa2Default from './fa2-default.json';
+import fa3Default from './fa3-default.json';
+import upo42 from './upo-4_2.json';
+import upo43 from './upo-4_3.json';
+
+// Built-ins are validated at load — a drift in one of our own presets fails fast
+// on import rather than silently producing a broken PDF.
+export const BUILTIN_TEMPLATES: Record<string, InvoiceTemplate> = {
+  'fa2-default': validateTemplate(fa2Default),
+  'fa3-default': validateTemplate(fa3Default),
+  'upo-4_2': validateTemplate(upo42),
+  'upo-4_3': validateTemplate(upo43),
+};
+
+export function getBuiltinTemplate(name: string): InvoiceTemplate | undefined {
+  return BUILTIN_TEMPLATES[name];
+}
+
+export function builtinTemplateNames(): string[] {
+  return Object.keys(BUILTIN_TEMPLATES);
+}
diff --git a/packages/ksef-client-ts/src/pdf/template/builtin/upo-4_2.json b/packages/ksef-client-ts/src/pdf/template/builtin/upo-4_2.json
new file mode 100644
index 0000000..a559468
--- /dev/null
+++ b/packages/ksef-client-ts/src/pdf/template/builtin/upo-4_2.json
@@ -0,0 +1,43 @@
+{
+  "schema": "UPO(4.2)",
+  "page": { "size": "A4", "margins": [40, 40, 40, 40] },
+  "styles": {
+    "title": { "fontSize": 16, "bold": true },
+    "fieldLabel": { "bold": true, "color": "#444444" },
+    "muted": { "color": "#666666" }
+  },
+  "blocks": [
+    { "type": "header", "title": { "label": "upoTitle" } },
+    { "type": "divider" },
+    { "type": "spacer", "height": 10 },
+    {
+      "type": "stack",
+      "stack": [
+        { "type": "columns", "columns": [
+          { "type": "text", "label": "sessionRef", "style": "fieldLabel" },
+          { "type": "text", "path": "NumerReferencyjnySesji" }
+        ] },
+        { "type": "columns", "columns": [
+          { "type": "text", "label": "ksefDocNumber", "style": "fieldLabel" },
+          { "type": "text", "path": "Dokument.NumerKSeFDokumentu" }
+        ] },
+        { "type": "columns", "columns": [
+          { "type": "text", "label": "invoiceNumber", "style": "fieldLabel" },
+          { "type": "text", "path": "Dokument.NumerFaktury" }
+        ] },
+        { "type": "columns", "columns": [
+          { "type": "text", "label": "issueDate", "style": "fieldLabel" },
+          { "type": "text", "path": "Dokument.DataWystawieniaFaktury", "format": "date" }
+        ] },
+        { "type": "columns", "columns": [
+          { "type": "text", "label": "receiptDate", "style": "fieldLabel" },
+          { "type": "text", "path": "Dokument.DataNadaniaNumeruKSeF", "format": "date" }
+        ] },
+        { "type": "columns", "columns": [
+          { "type": "text", "label": "documentHash", "style": "fieldLabel" },
+          { "type": "text", "path": "Dokument.SkrotDokumentu", "style": "muted" }
+        ] }
+      ]
+    }
+  ]
+}
diff --git a/packages/ksef-client-ts/src/pdf/template/builtin/upo-4_3.json b/packages/ksef-client-ts/src/pdf/template/builtin/upo-4_3.json
new file mode 100644
index 0000000..f62a197
--- /dev/null
+++ b/packages/ksef-client-ts/src/pdf/template/builtin/upo-4_3.json
@@ -0,0 +1,43 @@
+{
+  "schema": "UPO(4.3)",
+  "page": { "size": "A4", "margins": [40, 40, 40, 40] },
+  "styles": {
+    "title": { "fontSize": 16, "bold": true },
+    "fieldLabel": { "bold": true, "color": "#444444" },
+    "muted": { "color": "#666666" }
+  },
+  "blocks": [
+    { "type": "header", "title": { "label": "upoTitle" } },
+    { "type": "divider" },
+    { "type": "spacer", "height": 10 },
+    {
+      "type": "stack",
+      "stack": [
+        { "type": "columns", "columns": [
+          { "type": "text", "label": "sessionRef", "style": "fieldLabel" },
+          { "type": "text", "path": "NumerReferencyjnySesji" }
+        ] },
+        { "type": "columns", "columns": [
+          { "type": "text", "label": "ksefDocNumber", "style": "fieldLabel" },
+          { "type": "text", "path": "Dokument.NumerKSeFDokumentu" }
+        ] },
+        { "type": "columns", "columns": [
+          { "type": "text", "label": "invoiceNumber", "style": "fieldLabel" },
+          { "type": "text", "path": "Dokument.NumerFaktury" }
+        ] },
+        { "type": "columns", "columns": [
+          { "type": "text", "label": "issueDate", "style": "fieldLabel" },
+          { "type": "text", "path": "Dokument.DataWystawieniaFaktury", "format": "date" }
+        ] },
+        { "type": "columns", "columns": [
+          { "type": "text", "label": "receiptDate", "style": "fieldLabel" },
+          { "type": "text", "path": "Dokument.DataNadaniaNumeruKSeF", "format": "date" }
+        ] },
+        { "type": "columns", "columns": [
+          { "type": "text", "label": "documentHash", "style": "fieldLabel" },
+          { "type": "text", "path": "Dokument.SkrotDokumentu", "style": "muted" }
+        ] }
+      ]
+    }
+  ]
+}
diff --git a/packages/ksef-client-ts/src/pdf/template/dsl.ts b/packages/ksef-client-ts/src/pdf/template/dsl.ts
new file mode 100644
index 0000000..bbf7a87
--- /dev/null
+++ b/packages/ksef-client-ts/src/pdf/template/dsl.ts
@@ -0,0 +1,311 @@
+/**
+ * Template DSL — the declarative block language interpreted into a pdfmake
+ * document. Deliberately not Turing-complete: blocks + bindings + repeaters +
+ * conditions + formatters, nothing else. The block-type set is frozen; custom
+ * layouts compose primitives rather than register code.
+ *
+ * A binding is a dot-path string (see {@link file://../accessor.ts}); a `when`
+ * is a presence test; a `format` names a value formatter.
+ */
+import { z } from 'zod';
+import { KSeFValidationError } from '../../errors/ksef-validation-error.js';
+import type { FormatterName } from '../format.js';
+
+export type TemplateSchemaId = 'FA(2)' | 'FA(3)' | 'UPO(4.2)' | 'UPO(4.3)';
+
+/** Loose style bag mapping to pdfmake style props (fontSize, bold, color, …). */
+export type Style = Record<string, string | number | boolean | Array<number>>;
+
+export interface PageConfig {
+  size?: string;
+  orientation?: 'portrait' | 'landscape';
+  margins?: [number, number, number, number];
+}
+
+/** A labeled reference: `{ label }` resolves via i18n, `{ text }` is literal. */
+export interface LabelRef {
+  label?: string;
+  text?: string;
+}
+
+/** A column/field: label (i18n key) + binding path, optional formatter. */
+export interface FieldDef {
+  label: string;
+  path: string;
+  format?: FormatterName;
+  style?: string;
+}
+
+// ── Semantic blocks ────────────────────────────────────────────────────────
+
+export interface HeaderBlock {
+  type: 'header';
+  logo?: string;
+  title?: LabelRef;
+  number?: string;
+  date?: string;
+  style?: string;
+}
+
+export interface PartyColumn {
+  label: string;
+  fields: string[];
+}
+
+export interface PartiesBlock {
+  type: 'parties';
+  left: PartyColumn;
+  right: PartyColumn;
+  style?: string;
+}
+
+export interface LinesBlock {
+  type: 'lines';
+  from: string;
+  columns: FieldDef[];
+  style?: string;
+}
+
+export interface TotalsBlock {
+  type: 'totals';
+  rows: FieldDef[];
+  style?: string;
+}
+
+export interface PaymentBlock {
+  type: 'payment';
+  when?: string;
+  rows: FieldDef[];
+  style?: string;
+}
+
+export interface AnnotationsBlock {
+  type: 'annotations';
+  fields: FieldDef[];
+  style?: string;
+}
+
+export interface QrBlock {
+  type: 'qr';
+  when?: string;
+  fit?: number;
+}
+
+export interface FooterBlock {
+  type: 'footer';
+  label?: string;
+  text?: string;
+  style?: string;
+}
+
+// ── Primitive blocks ───────────────────────────────────────────────────────
+
+export interface TextBlock {
+  type: 'text';
+  text?: string;
+  path?: string;
+  label?: string;
+  format?: FormatterName;
+  when?: string;
+  style?: string;
+}
+
+export interface ColumnsBlock {
+  type: 'columns';
+  columns: Block[];
+  when?: string;
+  style?: string;
+}
+
+export interface StackBlock {
+  type: 'stack';
+  stack: Block[];
+  when?: string;
+  style?: string;
+}
+
+export interface TableBlock {
+  type: 'table';
+  from?: string;
+  columns: FieldDef[];
+  headers?: boolean;
+  when?: string;
+  style?: string;
+}
+
+export interface ImageBlock {
+  type: 'image';
+  src?: string;
+  path?: string;
+  width?: number;
+  when?: string;
+}
+
+export interface DividerBlock {
+  type: 'divider';
+  style?: string;
+}
+
+export interface SpacerBlock {
+  type: 'spacer';
+  height?: number;
+}
+
+export type Block =
+  | HeaderBlock
+  | PartiesBlock
+  | LinesBlock
+  | TotalsBlock
+  | PaymentBlock
+  | AnnotationsBlock
+  | QrBlock
+  | FooterBlock
+  | TextBlock
+  | ColumnsBlock
+  | StackBlock
+  | TableBlock
+  | ImageBlock
+  | DividerBlock
+  | SpacerBlock;
+
+export type BlockType = Block['type'];
+
+export interface InvoiceTemplate {
+  /** Binds this template to one XML kind; the engine rejects a version mismatch. */
+  schema: TemplateSchemaId;
+  page?: PageConfig;
+  defaultStyle?: Style;
+  styles?: Record<string, Style>;
+  /** Per-template label overrides (merged over the i18n bundle). */
+  labels?: Record<string, string>;
+  blocks: Block[];
+}
+
+// ── zod validation ─────────────────────────────────────────────────────────
+
+const formatEnum = z.enum(['money', 'date', 'number', 'nip']);
+const styleValue = z.union([z.string(), z.number(), z.boolean(), z.array(z.number())]);
+const styleSchema = z.record(z.string(), styleValue);
+const labelRef = z.object({ label: z.string().optional(), text: z.string().optional() }).strict();
+const fieldDef = z
+  .object({
+    label: z.string(),
+    path: z.string(),
+    format: formatEnum.optional(),
+    style: z.string().optional(),
+  })
+  .strict();
+
+// Recursive block schema (containers embed blocks). z.lazy breaks the cycle.
+const blockSchema: z.ZodType<Block> = z.lazy(() =>
+  z.discriminatedUnion('type', [
+    z.object({
+      type: z.literal('header'),
+      logo: z.string().optional(),
+      title: labelRef.optional(),
+      number: z.string().optional(),
+      date: z.string().optional(),
+      style: z.string().optional(),
+    }).strict(),
+    z.object({
+      type: z.literal('parties'),
+      left: z.object({ label: z.string(), fields: z.array(z.string()) }).strict(),
+      right: z.object({ label: z.string(), fields: z.array(z.string()) }).strict(),
+      style: z.string().optional(),
+    }).strict(),
+    z.object({
+      type: z.literal('lines'),
+      from: z.string(),
+      columns: z.array(fieldDef),
+      style: z.string().optional(),
+    }).strict(),
+    z.object({ type: z.literal('totals'), rows: z.array(fieldDef), style: z.string().optional() }).strict(),
+    z.object({
+      type: z.literal('payment'),
+      when: z.string().optional(),
+      rows: z.array(fieldDef),
+      style: z.string().optional(),
+    }).strict(),
+    z.object({ type: z.literal('annotations'), fields: z.array(fieldDef), style: z.string().optional() }).strict(),
+    z.object({ type: z.literal('qr'), when: z.string().optional(), fit: z.number().optional() }).strict(),
+    z.object({
+      type: z.literal('footer'),
+      label: z.string().optional(),
+      text: z.string().optional(),
+      style: z.string().optional(),
+    }).strict(),
+    z.object({
+      type: z.literal('text'),
+      text: z.string().optional(),
+      path: z.string().optional(),
+      label: z.string().optional(),
+      format: formatEnum.optional(),
+      when: z.string().optional(),
+      style: z.string().optional(),
+    }).strict(),
+    z.object({
+      type: z.literal('columns'),
+      columns: z.array(blockSchema),
+      when: z.string().optional(),
+      style: z.string().optional(),
+    }).strict(),
+    z.object({
+      type: z.literal('stack'),
+      stack: z.array(blockSchema),
+      when: z.string().optional(),
+      style: z.string().optional(),
+    }).strict(),
+    z.object({
+      type: z.literal('table'),
+      from: z.string().optional(),
+      columns: z.array(fieldDef),
+      headers: z.boolean().optional(),
+      when: z.string().optional(),
+      style: z.string().optional(),
+    }).strict(),
+    z.object({
+      type: z.literal('image'),
+      src: z.string().optional(),
+      path: z.string().optional(),
+      width: z.number().optional(),
+      when: z.string().optional(),
+    }).strict(),
+    z.object({ type: z.literal('divider'), style: z.string().optional() }).strict(),
+    z.object({ type: z.literal('spacer'), height: z.number().optional() }).strict(),
+  ]),
+) as z.ZodType<Block>;
+
+export const invoiceTemplateSchema: z.ZodType<InvoiceTemplate> = z
+  .object({
+    schema: z.enum(['FA(2)', 'FA(3)', 'UPO(4.2)', 'UPO(4.3)']),
+    page: z
+      .object({
+        size: z.string().optional(),
+        orientation: z.enum(['portrait', 'landscape']).optional(),
+        margins: z.tuple([z.number(), z.number(), z.number(), z.number()]).optional(),
+      })
+      .strict()
+      .optional(),
+    defaultStyle: styleSchema.optional(),
+    styles: z.record(z.string(), styleSchema).optional(),
+    labels: z.record(z.string(), z.string()).optional(),
+    blocks: z.array(blockSchema),
+  })
+  .strict() as z.ZodType<InvoiceTemplate>;
+
+/**
+ * Validate an untrusted template object. Throws {@link KSeFValidationError}
+ * (with a flattened, path-tagged message per issue) on any structural problem —
+ * unknown block type, missing required field, or extra keys.
+ */
+export function validateTemplate(input: unknown): InvoiceTemplate {
+  const result = invoiceTemplateSchema.safeParse(input);
+  if (!result.success) {
+    const messages = result.error.issues.map((issue) => {
+      const path = issue.path.length > 0 ? issue.path.join('.') : '(root)';
+      return `${path}: ${issue.message}`;
+    });
+    throw KSeFValidationError.fromMessages(messages);
+  }
+  return result.data;
+}
diff --git a/packages/ksef-client-ts/src/pdf/template/interpret.ts b/packages/ksef-client-ts/src/pdf/template/interpret.ts
new file mode 100644
index 0000000..4331542
--- /dev/null
+++ b/packages/ksef-client-ts/src/pdf/template/interpret.ts
@@ -0,0 +1,175 @@
+/**
+ * DSL interpreter: walks a validated {@link InvoiceTemplate} and emits a pdfmake
+ * document-definition content tree. Blocks are dispatched through a registry so
+ * renderers can be authored independently; containers recurse through a
+ * depth-guarded `render` callback rather than importing the interpreter, which
+ * keeps the module graph acyclic.
+ *
+ * Nodes are typed loosely (`PdfNode`) on purpose — the public `./pdf` types must
+ * not depend on `@types/pdfmake` (the optional peer). We assert node *structure*
+ * in tests, never bytes.
+ */
+import { get, has } from '../accessor.js';
+import { applyFormat, type FormatterName } from '../format.js';
+import { KSeFPdfError } from '../errors.js';
+import type { LabelResolver } from '../i18n/index.js';
+import type { Block, BlockType, InvoiceTemplate, Style } from './dsl.js';
+
+/** A pdfmake content node — a string or a property bag. Intentionally loose. */
+export type PdfNode = string | Record<string, unknown>;
+export type PdfContent = PdfNode | PdfNode[];
+
+/** Maximum block-nesting depth before the interpreter bails out. */
+export const MAX_DEPTH = 24;
+
+/** Derived, non-XML bindings (computed aliases + resolved options). */
+export interface RenderContext {
+  /** Parsed XML root (compact object). */
+  root: unknown;
+  /** Throw on a missing binding instead of yielding `''`. */
+  strict: boolean;
+  /** i18n label resolver bound to the chosen locale. */
+  label: LabelResolver;
+  /**
+   * Non-XML bindings by exact key: `opts.logo`, `opts.ksefNumber`, `hash`,
+   * `qrUrl`, `hasKsefNumber`, … . Looked up before falling through to XML.
+   */
+  bindings: Record<string, string>;
+  /** Boolean aliases for `when` (e.g. `hasKsefNumber`, `qr`). */
+  flags: Record<string, boolean>;
+}
+
+/** Recurse into a child block (depth-guarded); `null` when the child is hidden. */
+export type RenderChild = (child: Block) => PdfContent | null;
+
+/** A block renderer: pure (block, ctx) → pdfmake node(s), or `null` if hidden. */
+export type BlockRenderer<B extends Block = Block> = (
+  block: B,
+  ctx: RenderContext,
+  render: RenderChild,
+) => PdfContent | null;
+
+export type BlockRegistry = Partial<Record<BlockType, BlockRenderer>>;
+
+/** Resolve a binding path across the three namespaces (non-XML, then XML). */
+export function resolveBinding(path: string, ctx: RenderContext): string {
+  if (path in ctx.bindings) return ctx.bindings[path] ?? '';
+  return get(ctx.root, path, ctx.strict);
+}
+
+/** Evaluate a `when` condition: a boolean alias, else an XML presence test. */
+export function evalWhen(when: string | undefined, ctx: RenderContext): boolean {
+  if (when === undefined) return true;
+  if (when in ctx.flags) return ctx.flags[when] === true;
+  if (when in ctx.bindings) return (ctx.bindings[when] ?? '') !== '';
+  return has(ctx.root, when);
+}
+
+/** Read a `{ label }`/`{ text }` ref or a literal binding into a string. */
+export function resolveText(
+  spec: { text?: string; path?: string; label?: string; format?: FormatterName } | undefined,
+  ctx: RenderContext,
+): string {
+  if (!spec) return '';
+  if (spec.label !== undefined) return ctx.label(spec.label);
+  if (spec.text !== undefined) return spec.text;
+  if (spec.path !== undefined) return applyFormat(resolveBinding(spec.path, ctx), spec.format);
+  return '';
+}
+
+function withStyle(node: Record<string, unknown>, style: string | undefined): PdfNode {
+  return style ? { ...node, style } : node;
+}
+
+// ── Core (interpreter-native) primitive renderers ──────────────────────────
+
+const coreRegistry: BlockRegistry = {
+  text: (block, ctx) => {
+    const b = block as import('./dsl.js').TextBlock;
+    return withStyle({ text: resolveText(b, ctx) }, b.style);
+  },
+
+  stack: (block, _ctx, render) => {
+    const b = block as import('./dsl.js').StackBlock;
+    const stack = b.stack.map((c) => render(c)).filter((n): n is PdfContent => n !== null).flat();
+    return withStyle({ stack }, b.style);
+  },
+
+  columns: (block, _ctx, render) => {
+    const b = block as import('./dsl.js').ColumnsBlock;
+    const columns = b.columns.map((c) => render(c)).filter((n): n is PdfContent => n !== null).flat();
+    return withStyle({ columns }, b.style);
+  },
+
+  divider: (block) => {
+    const b = block as import('./dsl.js').DividerBlock;
+    return withStyle(
+      { canvas: [{ type: 'line', x1: 0, y1: 0, x2: 515, y2: 0, lineWidth: 0.5, lineColor: '#cccccc' }] },
+      b.style,
+    );
+  },
+
+  spacer: (block) => {
+    const b = block as import('./dsl.js').SpacerBlock;
+    return { text: '', margin: [0, (b.height ?? 8) / 2, 0, (b.height ?? 8) / 2] };
+  },
+};
+
+/**
+ * Interpret one block. Enforces the depth limit, resolves the renderer from the
+ * registry (unknown type → error), and hands the renderer a depth-incremented
+ * `render` callback for its children.
+ */
+export function interpretBlock(
+  block: Block,
+  ctx: RenderContext,
+  registry: BlockRegistry,
+  depth: number,
+): PdfContent | null {
+  if (depth > MAX_DEPTH) {
+    throw new KSeFPdfError(`Template nesting exceeds the maximum depth of ${MAX_DEPTH}`);
+  }
+  // `when` is handled centrally: a hidden block never reaches its renderer, so
+  // renderers stay free of visibility logic.
+  const when = (block as { when?: string }).when;
+  if (when !== undefined && !evalWhen(when, ctx)) return null;
+
+  const renderer = registry[block.type];
+  if (!renderer) {
+    throw new KSeFPdfError(`No renderer registered for block type "${block.type}"`);
+  }
+  const render: RenderChild = (child) => interpretBlock(child, ctx, registry, depth + 1);
+  return renderer(block, ctx, render);
+}
+
+/**
+ * Interpret a whole template into a pdfmake document definition. Merges the
+ * caller-provided renderers over the core primitives, wires template styles,
+ * and forces the bundled Roboto font (the only font shipped in the VFS).
+ */
+export function interpretTemplate(
+  template: InvoiceTemplate,
+  ctx: RenderContext,
+  registry: BlockRegistry = {},
+): Record<string, unknown> {
+  const merged: BlockRegistry = { ...coreRegistry, ...registry };
+  const content: PdfNode[] = [];
+  for (const block of template.blocks) {
+    const node = interpretBlock(block, ctx, merged, 0);
+    if (node === null) continue;
+    if (Array.isArray(node)) content.push(...node);
+    else content.push(node);
+  }
+
+  const defaultStyle: Style = { font: 'Roboto', fontSize: 9, ...(template.defaultStyle ?? {}) };
+  const doc: Record<string, unknown> = { content, defaultStyle };
+  if (template.styles) doc.styles = template.styles;
+  if (template.page) {
+    if (template.page.size) doc.pageSize = template.page.size;
+    if (template.page.orientation) doc.pageOrientation = template.page.orientation;
+    if (template.page.margins) doc.pageMargins = template.page.margins;
+  }
+  return doc;
+}
+
+export { coreRegistry };
diff --git a/packages/ksef-client-ts/tests/fixtures/pdf-types-check.ts b/packages/ksef-client-ts/tests/fixtures/pdf-types-check.ts
new file mode 100644
index 0000000..42a5e53
--- /dev/null
+++ b/packages/ksef-client-ts/tests/fixtures/pdf-types-check.ts
@@ -0,0 +1,41 @@
+/**
+ * Type-only fixture for the `ksef-client-ts/pdf` subpath.
+ *
+ * Compiled by `tsc --project tsconfig.pdf-check.json --noEmit` with `types`
+ * restricted to `node` (NO `@types/pdfmake` in scope). It proves that the
+ * public `./pdf` types resolve for a consumer who has NOT installed pdfmake —
+ * the optional peer must never leak into the published type surface.
+ *
+ * This file is NOT executed at runtime.
+ */
+import {
+  renderInvoicePdf,
+  renderInvoicePdfFromFile,
+  renderInvoicePdfFromTemplate,
+  renderUpoPdf,
+  detectInvoiceVersion,
+  detectUpoVersion,
+  type Locale,
+  type InvoiceTemplate,
+  type RenderOptions,
+} from 'ksef-client-ts/pdf';
+
+const xml = '<Faktura/>';
+const opts: RenderOptions = { locale: 'pl+en', qr: true, strict: false };
+
+const _a: Promise<Uint8Array> = renderInvoicePdf(xml, 'fa3-default', opts);
+const _b: Promise<Uint8Array> = renderInvoicePdfFromFile(xml, './tpl.json', opts);
+void _a; void _b;
+
+const template: InvoiceTemplate = {
+  schema: 'FA(3)',
+  blocks: [{ type: 'text', path: 'Fa.P_2' }],
+};
+const _c: Promise<Uint8Array> = renderInvoicePdfFromTemplate(new Uint8Array(), template);
+const _d: Promise<Uint8Array> = renderUpoPdf(xml);
+void _c; void _d;
+
+const _loc: Locale = 'en';
+const _iv: 'FA(2)' | 'FA(3)' | null = detectInvoiceVersion(xml);
+const _uv: 'UPO(4.2)' | 'UPO(4.3)' | null = detectUpoVersion(xml);
+void _loc; void _iv; void _uv;
diff --git a/packages/ksef-client-ts/tests/fixtures/pdf/fa2.xml b/packages/ksef-client-ts/tests/fixtures/pdf/fa2.xml
new file mode 100644
index 0000000..2e03abd
--- /dev/null
+++ b/packages/ksef-client-ts/tests/fixtures/pdf/fa2.xml
@@ -0,0 +1,75 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Synthetic, fully anonymous FA(2) fixture for PDF-renderer tests. No real taxpayer data. -->
+<Faktura xmlns="http://crd.gov.pl/wzor/2023/06/29/12648/"
+         xmlns:etd="http://crd.gov.pl/xml/schematy/dziedzinowe/mf/2022/01/05/eD/DefinicjeTypy/"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
+    <Naglowek>
+        <KodFormularza kodSystemowy="FA (2)" wersjaSchemy="1-0E">FA</KodFormularza>
+        <WariantFormularza>2</WariantFormularza>
+        <DataWytworzeniaFa>2025-01-15T10:00:00Z</DataWytworzeniaFa>
+        <SystemInfo>anonymous test fixture</SystemInfo>
+    </Naglowek>
+    <Podmiot1>
+        <DaneIdentyfikacyjne>
+            <NIP>1111111111</NIP>
+            <Nazwa>Sprzedawca Przykładowy Sp. z o.o.</Nazwa>
+        </DaneIdentyfikacyjne>
+        <Adres>
+            <KodKraju>PL</KodKraju>
+            <AdresL1>ul. Przykładowa 1</AdresL1>
+            <AdresL2>00-001 Warszawa</AdresL2>
+        </Adres>
+    </Podmiot1>
+    <Podmiot2>
+        <DaneIdentyfikacyjne>
+            <NIP>2222222222</NIP>
+            <Nazwa>Nabywca Przykładowy S.A.</Nazwa>
+        </DaneIdentyfikacyjne>
+        <Adres>
+            <KodKraju>PL</KodKraju>
+            <AdresL1>ul. Testowa 2</AdresL1>
+            <AdresL2>00-002 Kraków</AdresL2>
+        </Adres>
+    </Podmiot2>
+    <Fa>
+        <KodWaluty>PLN</KodWaluty>
+        <P_1>2025-01-15</P_1>
+        <P_1M>Warszawa</P_1M>
+        <P_2>FA/2025/01/001</P_2>
+        <P_6>2025-01-15</P_6>
+        <P_13_1>500.00</P_13_1>
+        <P_14_1>115.00</P_14_1>
+        <P_15>615.00</P_15>
+        <Adnotacje>
+            <P_16>2</P_16>
+            <P_17>2</P_17>
+            <P_18>2</P_18>
+            <P_18A>2</P_18A>
+            <Zwolnienie>
+                <P_19N>1</P_19N>
+            </Zwolnienie>
+            <NoweSrodkiTransportu>
+                <P_22N>1</P_22N>
+            </NoweSrodkiTransportu>
+            <P_23>2</P_23>
+            <PMarzy>
+                <P_PMarzyN>1</P_PMarzyN>
+            </PMarzy>
+        </Adnotacje>
+        <RodzajFaktury>VAT</RodzajFaktury>
+        <FaWiersz>
+            <NrWierszaFa>1</NrWierszaFa>
+            <P_7>Usługa przykładowa</P_7>
+            <P_8A>szt.</P_8A>
+            <P_8B>5</P_8B>
+            <P_9A>100.00</P_9A>
+            <P_11>500.00</P_11>
+            <P_12>23</P_12>
+        </FaWiersz>
+        <Platnosc>
+            <Zaplacono>1</Zaplacono>
+            <DataZaplaty>2025-01-15</DataZaplaty>
+            <FormaPlatnosci>6</FormaPlatnosci>
+        </Platnosc>
+    </Fa>
+</Faktura>
diff --git a/packages/ksef-client-ts/tests/fixtures/pdf/fa3.xml b/packages/ksef-client-ts/tests/fixtures/pdf/fa3.xml
new file mode 100644
index 0000000..b19d3cd
--- /dev/null
+++ b/packages/ksef-client-ts/tests/fixtures/pdf/fa3.xml
@@ -0,0 +1,75 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Synthetic, fully anonymous FA(3) fixture for PDF-renderer tests. No real taxpayer data. -->
+<Faktura xmlns="http://crd.gov.pl/wzor/2025/06/25/13775/"
+         xmlns:etd="http://crd.gov.pl/xml/schematy/dziedzinowe/mf/2022/01/05/eD/DefinicjeTypy/"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
+    <Naglowek>
+        <KodFormularza kodSystemowy="FA (3)" wersjaSchemy="1-0E">FA</KodFormularza>
+        <WariantFormularza>3</WariantFormularza>
+        <DataWytworzeniaFa>2025-01-15T10:00:00Z</DataWytworzeniaFa>
+        <SystemInfo>anonymous test fixture</SystemInfo>
+    </Naglowek>
+    <Podmiot1>
+        <DaneIdentyfikacyjne>
+            <NIP>1111111111</NIP>
+            <Nazwa>Sprzedawca Przykładowy Sp. z o.o.</Nazwa>
+        </DaneIdentyfikacyjne>
+        <Adres>
+            <KodKraju>PL</KodKraju>
+            <AdresL1>ul. Przykładowa 1</AdresL1>
+            <AdresL2>00-001 Warszawa</AdresL2>
+        </Adres>
+    </Podmiot1>
+    <Podmiot2>
+        <DaneIdentyfikacyjne>
+            <NIP>2222222222</NIP>
+            <Nazwa>Nabywca Przykładowy S.A.</Nazwa>
+        </DaneIdentyfikacyjne>
+        <Adres>
+            <KodKraju>PL</KodKraju>
+            <AdresL1>ul. Testowa 2</AdresL1>
+            <AdresL2>00-002 Kraków</AdresL2>
+        </Adres>
+    </Podmiot2>
+    <Fa>
+        <KodWaluty>PLN</KodWaluty>
+        <P_1>2025-01-15</P_1>
+        <P_1M>Warszawa</P_1M>
+        <P_2>FA/2025/01/001</P_2>
+        <P_6>2025-01-15</P_6>
+        <P_13_1>500.00</P_13_1>
+        <P_14_1>115.00</P_14_1>
+        <P_15>615.00</P_15>
+        <Adnotacje>
+            <P_16>2</P_16>
+            <P_17>2</P_17>
+            <P_18>2</P_18>
+            <P_18A>2</P_18A>
+            <Zwolnienie>
+                <P_19N>1</P_19N>
+            </Zwolnienie>
+            <NoweSrodkiTransportu>
+                <P_22N>1</P_22N>
+            </NoweSrodkiTransportu>
+            <P_23>2</P_23>
+            <PMarzy>
+                <P_PMarzyN>1</P_PMarzyN>
+            </PMarzy>
+        </Adnotacje>
+        <RodzajFaktury>VAT</RodzajFaktury>
+        <FaWiersz>
+            <NrWierszaFa>1</NrWierszaFa>
+            <P_7>Usługa przykładowa</P_7>
+            <P_8A>szt.</P_8A>
+            <P_8B>5</P_8B>
+            <P_9A>100.00</P_9A>
+            <P_11>500.00</P_11>
+            <P_12>23</P_12>
+        </FaWiersz>
+        <Platnosc>
+            <Zaplacono>1</Zaplacono>
+            <DataZaplaty>2025-01-15</DataZaplaty>
+            <FormaPlatnosci>6</FormaPlatnosci>
+        </Platnosc>
+    </Fa>
+</Faktura>
diff --git a/packages/ksef-client-ts/tests/fixtures/pdf/upo-4_2.xml b/packages/ksef-client-ts/tests/fixtures/pdf/upo-4_2.xml
new file mode 100644
index 0000000..dba4b45
--- /dev/null
+++ b/packages/ksef-client-ts/tests/fixtures/pdf/upo-4_2.xml
@@ -0,0 +1,24 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Synthetic, fully anonymous UPO(4.2) fixture for PDF-renderer tests. No real data. -->
+<Potwierdzenie xmlns="http://upo.schematy.mf.gov.pl/KSeF/v4-2">
+	<NazwaPodmiotuPrzyjmujacego>Ministerstwo Finansów (środowisko testowe)</NazwaPodmiotuPrzyjmujacego>
+	<NumerReferencyjnySesji>22222222-22-2222222222-2222222222-22</NumerReferencyjnySesji>
+	<Uwierzytelnienie>
+		<IdKontekstu>
+			<IdWewnetrzny>1111111111-00000</IdWewnetrzny>
+		</IdKontekstu>
+		<NumerReferencyjnyTokenaKSeF>20250115-EX-0000000000-0000000000-00</NumerReferencyjnyTokenaKSeF>
+	</Uwierzytelnienie>
+	<NazwaStrukturyLogicznej>Schemat_FA(2)_v1-0E.xsd</NazwaStrukturyLogicznej>
+	<KodFormularza>FA (2)</KodFormularza>
+	<Dokument>
+		<NipSprzedawcy>1111111111</NipSprzedawcy>
+		<NumerKSeFDokumentu>1111111111-20250115-020000000000-00</NumerKSeFDokumentu>
+		<NumerFaktury>FA/2025/01/001</NumerFaktury>
+		<DataWystawieniaFaktury>2025-01-15</DataWystawieniaFaktury>
+		<DataPrzeslaniaDokumentu>2025-01-15T10:00:00.000+01:00</DataPrzeslaniaDokumentu>
+		<DataNadaniaNumeruKSeF>2025-01-15T10:00:01.000+01:00</DataNadaniaNumeruKSeF>
+		<SkrotDokumentu>BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB=</SkrotDokumentu>
+		<TrybWysylki>Online</TrybWysylki>
+	</Dokument>
+</Potwierdzenie>
diff --git a/packages/ksef-client-ts/tests/fixtures/pdf/upo-4_3.xml b/packages/ksef-client-ts/tests/fixtures/pdf/upo-4_3.xml
new file mode 100644
index 0000000..f12e4f4
--- /dev/null
+++ b/packages/ksef-client-ts/tests/fixtures/pdf/upo-4_3.xml
@@ -0,0 +1,24 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Synthetic, fully anonymous UPO(4.3) fixture for PDF-renderer tests. No real data. -->
+<Potwierdzenie xmlns="http://upo.schematy.mf.gov.pl/KSeF/v4-3">
+	<NazwaPodmiotuPrzyjmujacego>Ministerstwo Finansów (środowisko testowe)</NazwaPodmiotuPrzyjmujacego>
+	<NumerReferencyjnySesji>11111111-11-1111111111-1111111111-11</NumerReferencyjnySesji>
+	<Uwierzytelnienie>
+		<IdKontekstu>
+			<IdWewnetrzny>1111111111-00000</IdWewnetrzny>
+		</IdKontekstu>
+		<NumerReferencyjnyTokenaKSeF>20250115-EX-0000000000-0000000000-00</NumerReferencyjnyTokenaKSeF>
+	</Uwierzytelnienie>
+	<NazwaStrukturyLogicznej>Schemat_FA(3)_v1-0E.xsd</NazwaStrukturyLogicznej>
+	<KodFormularza>FA (3)</KodFormularza>
+	<Dokument>
+		<NipSprzedawcy>1111111111</NipSprzedawcy>
+		<NumerKSeFDokumentu>1111111111-20250115-010000000000-00</NumerKSeFDokumentu>
+		<NumerFaktury>FA/2025/01/001</NumerFaktury>
+		<DataWystawieniaFaktury>2025-01-15</DataWystawieniaFaktury>
+		<DataPrzeslaniaDokumentu>2025-01-15T10:00:00.000+01:00</DataPrzeslaniaDokumentu>
+		<DataNadaniaNumeruKSeF>2025-01-15T10:00:01.000+01:00</DataNadaniaNumeruKSeF>
+		<SkrotDokumentu>AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=</SkrotDokumentu>
+		<TrybWysylki>Online</TrybWysylki>
+	</Dokument>
+</Potwierdzenie>
diff --git a/packages/ksef-client-ts/tests/unit/cli/commands/invoice-pdf.test.ts b/packages/ksef-client-ts/tests/unit/cli/commands/invoice-pdf.test.ts
new file mode 100644
index 0000000..719d9fe
--- /dev/null
+++ b/packages/ksef-client-ts/tests/unit/cli/commands/invoice-pdf.test.ts
@@ -0,0 +1,186 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import * as fs from 'node:fs';
+import { invoiceCommand } from '../../../../src/cli/commands/invoice.js';
+import * as output from '../../../../src/cli/output.js';
+import * as pdfModule from '../../../../src/pdf/index.js';
+
+// Surface thrown errors instead of process.exit, so we can assert on them.
+vi.mock('../../../../src/cli/error-handler.js', () => ({
+  withErrorHandler: vi.fn((fn) => fn()),
+}));
+
+vi.mock('consola', () => ({
+  consola: { level: 0, start: vi.fn(), info: vi.fn(), success: vi.fn(), error: vi.fn(), log: vi.fn(), warn: vi.fn() },
+}));
+
+vi.mock('../../../../src/cli/client-factory.js', () => ({
+  requireSession: vi.fn(),
+  createClient: vi.fn(),
+}));
+
+vi.mock('../../../../src/cli/config-store.js', () => ({ loadConfig: vi.fn() }));
+
+vi.mock('../../../../src/cli/session-store.js', () => ({
+  saveOnlineSessionRef: vi.fn(),
+  clearOnlineSessionRef: vi.fn(),
+  loadEncryptionData: vi.fn(),
+}));
+
+vi.mock('../../../../src/cli/output.js', () => ({
+  outputResult: vi.fn(),
+  outputTable: vi.fn(),
+  outputSuccess: vi.fn(),
+  outputKeyValue: vi.fn(),
+  outputWarning: vi.fn(),
+}));
+
+vi.mock('../../../../src/validation/invoice-validator.js', () => ({
+  validate: vi.fn(),
+  validateBatch: vi.fn(),
+  batchValidationDetails: vi.fn(() => []),
+}));
+
+// The CLI lazily `import('../../pdf/index.js')`; vitest applies this mock to
+// that dynamic import too (same resolved module).
+vi.mock('../../../../src/pdf/index.js', () => ({
+  renderInvoicePdf: vi.fn(),
+  renderInvoicePdfFromFile: vi.fn(),
+  renderInvoicePdfFromTemplate: vi.fn(),
+  renderUpoPdf: vi.fn(),
+  detectInvoiceVersion: vi.fn(),
+  detectUpoVersion: vi.fn(),
+}));
+
+vi.mock('node:fs', () => {
+  const m = {
+    existsSync: vi.fn(),
+    readFileSync: vi.fn(),
+    writeFileSync: vi.fn(),
+    statSync: vi.fn(),
+    readdirSync: vi.fn(),
+    mkdirSync: vi.fn(),
+  };
+  return { ...m, default: m };
+});
+
+const mockedFs = vi.mocked(fs);
+const mockedPdf = vi.mocked(pdfModule);
+const mockedOutput = vi.mocked(output);
+
+const FAKE_PDF = new Uint8Array([0x25, 0x50, 0x44, 0x46]); // "%PDF"
+
+function runPdf(args: Record<string, unknown>) {
+  return (invoiceCommand.subCommands!.pdf as any).run!({ args });
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  // Sensible defaults: file exists, reads to an FA(3) buffer, renders to bytes.
+  mockedFs.existsSync.mockReturnValue(true);
+  mockedFs.readFileSync.mockReturnValue(Buffer.from('<Faktura/>'));
+  mockedPdf.detectInvoiceVersion.mockReturnValue('FA(3)');
+  mockedPdf.detectUpoVersion.mockReturnValue(null);
+  mockedPdf.renderInvoicePdf.mockResolvedValue(FAKE_PDF);
+  mockedPdf.renderInvoicePdfFromFile.mockResolvedValue(FAKE_PDF);
+  mockedPdf.renderUpoPdf.mockResolvedValue(FAKE_PDF);
+});
+
+describe('invoice pdf — CLI wiring', () => {
+  it('errors when the input file does not exist', async () => {
+    mockedFs.existsSync.mockReturnValue(false);
+    await expect(runPdf({ file: 'missing.xml' })).rejects.toThrow(/File not found/);
+  });
+
+  it('rejects when both --template and --template-file are given', async () => {
+    await expect(
+      runPdf({ file: 'invoice.xml', template: 'fa3-default', templateFile: './t.json' }),
+    ).rejects.toThrow(/mutually exclusive/);
+  });
+
+  it('rejects an invalid --locale', async () => {
+    await expect(runPdf({ file: 'invoice.xml', locale: 'de' })).rejects.toThrow(/Invalid --locale/);
+  });
+
+  it('defaults to fa3-default for an FA(3) document and writes next to the source', async () => {
+    await runPdf({ file: 'dir/invoice.xml' });
+    expect(mockedPdf.renderInvoicePdf).toHaveBeenCalledWith(
+      expect.any(Uint8Array),
+      'fa3-default',
+      expect.objectContaining({ locale: 'pl', qr: false }),
+    );
+    expect(mockedFs.writeFileSync).toHaveBeenCalledWith('dir/invoice.pdf', FAKE_PDF);
+    expect(mockedOutput.outputSuccess).toHaveBeenCalled();
+  });
+
+  it('defaults to fa2-default for an FA(2) document', async () => {
+    mockedPdf.detectInvoiceVersion.mockReturnValue('FA(2)');
+    await runPdf({ file: 'invoice.xml' });
+    expect(mockedPdf.renderInvoicePdf).toHaveBeenCalledWith(expect.any(Uint8Array), 'fa2-default', expect.anything());
+  });
+
+  it('uses a named built-in template with --template', async () => {
+    await runPdf({ file: 'invoice.xml', template: 'fa3-default' });
+    expect(mockedPdf.renderInvoicePdf).toHaveBeenCalledWith(expect.any(Uint8Array), 'fa3-default', expect.anything());
+  });
+
+  it('uses a custom template file with --template-file', async () => {
+    await runPdf({ file: 'invoice.xml', templateFile: './custom.json' });
+    expect(mockedPdf.renderInvoicePdfFromFile).toHaveBeenCalledWith(
+      expect.any(Uint8Array),
+      './custom.json',
+      expect.anything(),
+    );
+    expect(mockedPdf.renderInvoicePdf).not.toHaveBeenCalled();
+  });
+
+  it('honors an explicit --out path', async () => {
+    await runPdf({ file: 'invoice.xml', out: '/tmp/result.pdf' });
+    expect(mockedFs.writeFileSync).toHaveBeenCalledWith('/tmp/result.pdf', FAKE_PDF);
+  });
+
+  it('renders a UPO document when --upo is set', async () => {
+    await runPdf({ file: 'upo.xml', upo: true });
+    expect(mockedPdf.renderUpoPdf).toHaveBeenCalled();
+    expect(mockedPdf.renderInvoicePdf).not.toHaveBeenCalled();
+  });
+
+  it('auto-detects a UPO document (no invoice version, UPO version present)', async () => {
+    mockedPdf.detectInvoiceVersion.mockReturnValue(null);
+    mockedPdf.detectUpoVersion.mockReturnValue('UPO(4.3)');
+    await runPdf({ file: 'upo.xml' });
+    expect(mockedPdf.renderUpoPdf).toHaveBeenCalled();
+  });
+
+  it('passes qr / ksefNumber / env through to the renderer', async () => {
+    await runPdf({ file: 'invoice.xml', qr: true, ksefNumber: 'NR-1', env: 'test' });
+    expect(mockedPdf.renderInvoicePdf).toHaveBeenCalledWith(
+      expect.any(Uint8Array),
+      'fa3-default',
+      expect.objectContaining({ qr: true, ksefNumber: 'NR-1', env: 'test' }),
+    );
+  });
+
+  it('renders bilingual labels with --locale pl+en', async () => {
+    await runPdf({ file: 'invoice.xml', locale: 'pl+en' });
+    expect(mockedPdf.renderInvoicePdf).toHaveBeenCalledWith(
+      expect.any(Uint8Array),
+      'fa3-default',
+      expect.objectContaining({ locale: 'pl+en' }),
+    );
+  });
+
+  it('surfaces the friendly pdfmake-missing error from the module', async () => {
+    mockedPdf.renderInvoicePdf.mockRejectedValue(
+      new Error('PDF rendering requires the optional peer dependency "pdfmake". Install it with: npm i "pdfmake@^0.2.20"'),
+    );
+    await expect(runPdf({ file: 'invoice.xml' })).rejects.toThrow(/npm i "pdfmake\^?0?\.?2?\.?20?"|pdfmake@\^0\.2\.20/);
+  });
+
+  it('emits JSON output when --json is set', async () => {
+    await runPdf({ file: 'invoice.xml', json: true });
+    expect(mockedOutput.outputResult).toHaveBeenCalledWith(
+      expect.objectContaining({ out: 'invoice.pdf', bytes: FAKE_PDF.length }),
+      { json: true },
+    );
+  });
+});
diff --git a/packages/ksef-client-ts/tests/unit/pdf/accessor.test.ts b/packages/ksef-client-ts/tests/unit/pdf/accessor.test.ts
new file mode 100644
index 0000000..0fe07b2
--- /dev/null
+++ b/packages/ksef-client-ts/tests/unit/pdf/accessor.test.ts
@@ -0,0 +1,242 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, it, expect } from 'vitest';
+import { get, list, has, getNode } from '../../../src/pdf/accessor.js';
+import { parseXmlForPdf } from '../../../src/pdf/parse.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const fixturesDir = path.resolve(__dirname, '../../fixtures');
+
+function loadFixture(rel: string): string {
+  return fs.readFileSync(path.join(fixturesDir, rel), 'utf8');
+}
+
+// A synthetic, anonymous FA(3) invoice parsed through the compact PDF parser.
+// Used for the fixture-backed cases (nested scalar, attribute, #text unwrap,
+// collapsed list). No real taxpayer data.
+const fa3 = parseXmlForPdf(loadFixture('pdf/fa3.xml'));
+
+// A small, hand-built compact object exercising every parser artifact the
+// accessor must smooth over, without depending on a real file.
+const inline = {
+  Podmiot1: {
+    DaneIdentyfikacyjne: { NIP: '1111111111', Nazwa: 'Sprzedawca Przykładowy' },
+  },
+  // Mixed-content element: text under `#text`, plus attributes under `@`.
+  KodFormularza: { '#text': 'FA', '@kodSystemowy': 'FA (3)', '@wersjaSchemy': '1-0E' },
+  // Element with attributes only — no scalar value at all.
+  AttrsOnly: { '@code': 'X' },
+  // Element whose only child is an empty `#text`.
+  EmptyText: { '#text': '' },
+  // Element with `#text` alongside another key — not the "single #text" case.
+  TextPlus: { '#text': '', '@a': 'x' },
+  // Repeater the parser collapsed to an object (single element).
+  Collapsed: { Row: { n: '1' } },
+  // A genuine array (multi-element repeater) and an empty one.
+  Rows: [{ n: '1' }, { n: '2' }, { n: '3' }],
+  Empty: [] as unknown[],
+  // Array descent: reading through an array should follow the first element.
+  ArrDescent: [{ x: 'first' }, { x: 'second' }],
+  // Array whose first element carries mixed content — coerced via #text.
+  ArrText: [{ '#text': 'hi' }],
+  // Scalars of each primitive kind.
+  Str: 'hello',
+  EmptyStr: '',
+  Num: 5,
+  Zero: 0,
+  BoolTrue: true,
+  BoolFalse: false,
+  NullLeaf: null,
+};
+
+describe('getNode', () => {
+  it('returns the raw object at a nested path', () => {
+    const node = getNode(fa3, 'Faktura.Podmiot1.DaneIdentyfikacyjne');
+    expect(node).toEqual({ NIP: '1111111111', Nazwa: 'Sprzedawca Przykładowy Sp. z o.o.' });
+  });
+
+  it('returns the raw array node untouched', () => {
+    expect(getNode(inline, 'Rows')).toBe(inline.Rows);
+  });
+
+  it('returns the root when the path is empty (all segments filtered)', () => {
+    expect(getNode(inline, '')).toBe(inline);
+    // Leading/trailing/duplicate dots are filtered out too.
+    expect(getNode(inline, '.Str.')).toBe('hello');
+  });
+
+  it('follows the first element when descent hits an array mid-path', () => {
+    expect(getNode(inline, 'ArrDescent.x')).toBe('first');
+  });
+
+  it('returns undefined when an intermediate segment is missing', () => {
+    expect(getNode(inline, 'Podmiot1.Nope.NIP')).toBeUndefined();
+  });
+
+  it('returns undefined when descent runs into a scalar', () => {
+    expect(getNode(inline, 'Str.somethingDeeper')).toBeUndefined();
+  });
+
+  it('returns undefined for a null or undefined root', () => {
+    expect(getNode(null, 'a')).toBeUndefined();
+    expect(getNode(undefined, 'a')).toBeUndefined();
+  });
+
+  it('returns undefined when a leaf value is explicitly undefined', () => {
+    expect(getNode({ a: undefined }, 'a')).toBeUndefined();
+  });
+});
+
+describe('get', () => {
+  it('reads a nested scalar from a fixture', () => {
+    expect(get(fa3, 'Faktura.Podmiot1.DaneIdentyfikacyjne.NIP')).toBe('1111111111');
+  });
+
+  it('unwraps #text on a mixed-content element (fixture)', () => {
+    expect(get(fa3, 'Faktura.Naglowek.KodFormularza')).toBe('FA');
+  });
+
+  it('unwraps #text on a mixed-content element (inline)', () => {
+    expect(get(inline, 'KodFormularza')).toBe('FA');
+  });
+
+  it('reads an @attribute segment (fixture)', () => {
+    expect(get(fa3, 'Faktura.Naglowek.KodFormularza.@kodSystemowy')).toBe('FA (3)');
+  });
+
+  it('reads an @attribute segment (inline)', () => {
+    expect(get(inline, 'KodFormularza.@wersjaSchemy')).toBe('1-0E');
+  });
+
+  it('coerces a number leaf to a string', () => {
+    expect(get(inline, 'Num')).toBe('5');
+    expect(get(inline, 'Zero')).toBe('0');
+  });
+
+  it('coerces a boolean leaf to a string', () => {
+    expect(get(inline, 'BoolTrue')).toBe('true');
+    expect(get(inline, 'BoolFalse')).toBe('false');
+  });
+
+  it('returns "" for a leaf of an uncoercible type (e.g. bigint)', () => {
+    // Not a string/number/boolean/array/record — falls through to no scalar.
+    expect(get({ big: 10n }, 'big')).toBe('');
+  });
+
+  it('follows the first element when descending through an array', () => {
+    expect(get(inline, 'ArrDescent.x')).toBe('first');
+  });
+
+  it('coerces via the first array element (unwrapping its #text)', () => {
+    expect(get(inline, 'ArrText')).toBe('hi');
+  });
+
+  it('returns "" for an element that has only attributes (no scalar)', () => {
+    expect(get(inline, 'AttrsOnly')).toBe('');
+  });
+
+  it('returns "" for a missing path', () => {
+    expect(get(inline, 'Nope.Missing')).toBe('');
+  });
+
+  it('returns "" for a null leaf', () => {
+    expect(get(inline, 'NullLeaf')).toBe('');
+  });
+
+  it('returns "" for a null/undefined root', () => {
+    expect(get(null, 'a')).toBe('');
+    expect(get(undefined, 'a')).toBe('');
+  });
+
+  it('throws with the path in the message when strict and missing', () => {
+    expect(() => get(inline, 'Nope.Missing', true)).toThrow(/Missing binding: "Nope\.Missing"/);
+  });
+
+  it('does not throw in strict mode when the binding exists', () => {
+    expect(get(inline, 'Str', true)).toBe('hello');
+  });
+});
+
+describe('list', () => {
+  it('wraps a parser-collapsed single element into a 1-element array (fixture)', () => {
+    const rows = list(fa3, 'Faktura.Fa.FaWiersz');
+    expect(Array.isArray(rows)).toBe(true);
+    expect(rows).toHaveLength(1);
+    expect((rows[0] as Record<string, unknown>).NrWierszaFa).toBe('1');
+  });
+
+  it('wraps a collapsed object (inline) into a 1-element array', () => {
+    expect(list(inline, 'Collapsed.Row')).toEqual([{ n: '1' }]);
+  });
+
+  it('returns a real array unchanged (same reference)', () => {
+    const rows = list(inline, 'Rows');
+    expect(rows).toBe(inline.Rows);
+    expect(rows).toHaveLength(3);
+  });
+
+  it('returns [] for a missing path', () => {
+    expect(list(inline, 'Nope')).toEqual([]);
+  });
+
+  it('returns [] for a null leaf', () => {
+    expect(list(inline, 'NullLeaf')).toEqual([]);
+  });
+
+  it('returns [] for a null root', () => {
+    expect(list(null, 'a')).toEqual([]);
+  });
+});
+
+describe('has', () => {
+  it('is true for a present nested object (fixture)', () => {
+    expect(has(fa3, 'Faktura.Podmiot1')).toBe(true);
+  });
+
+  it('is true for a present non-empty scalar (fixture)', () => {
+    expect(has(fa3, 'Faktura.Fa.P_2')).toBe(true);
+  });
+
+  it('is true for a number leaf, including 0', () => {
+    expect(has(inline, 'Num')).toBe(true);
+    expect(has(inline, 'Zero')).toBe(true);
+  });
+
+  it('is true for a boolean leaf, including false', () => {
+    expect(has(inline, 'BoolTrue')).toBe(true);
+    expect(has(inline, 'BoolFalse')).toBe(true);
+  });
+
+  it('is true for a non-empty array', () => {
+    expect(has(inline, 'Rows')).toBe(true);
+  });
+
+  it('is true for an element carrying a non-empty #text only', () => {
+    expect(has({ K: { '#text': 'FA' } }, 'K')).toBe(true);
+  });
+
+  it('is true for an element with #text plus other keys', () => {
+    expect(has(inline, 'TextPlus')).toBe(true);
+  });
+
+  it('is false for a missing path', () => {
+    expect(has(inline, 'Nope')).toBe(false);
+  });
+
+  it('is false for a null leaf', () => {
+    expect(has(inline, 'NullLeaf')).toBe(false);
+  });
+
+  it('is false for an empty string', () => {
+    expect(has(inline, 'EmptyStr')).toBe(false);
+  });
+
+  it('is false for an empty array', () => {
+    expect(has(inline, 'Empty')).toBe(false);
+  });
+
+  it('is false for an element carrying only an empty #text', () => {
+    expect(has(inline, 'EmptyText')).toBe(false);
+  });
+});
diff --git a/packages/ksef-client-ts/tests/unit/pdf/blocks-primitive.test.ts b/packages/ksef-client-ts/tests/unit/pdf/blocks-primitive.test.ts
new file mode 100644
index 0000000..744d4e3
--- /dev/null
+++ b/packages/ksef-client-ts/tests/unit/pdf/blocks-primitive.test.ts
@@ -0,0 +1,150 @@
+import { describe, it, expect } from 'vitest';
+import { tableRenderer } from '../../../src/pdf/template/blocks/table.js';
+import { imageRenderer } from '../../../src/pdf/template/blocks/image.js';
+import type { RenderContext } from '../../../src/pdf/template/interpret.js';
+import type { ImageBlock, TableBlock } from '../../../src/pdf/template/dsl.js';
+
+/** Build a RenderContext by hand; label is identity so keys pass through. */
+function makeCtx(root: unknown, overrides: Partial<RenderContext> = {}): RenderContext {
+  return {
+    root,
+    strict: false,
+    label: (k: string) => k,
+    bindings: {},
+    flags: {},
+    ...overrides,
+  };
+}
+
+/** The interpreter passes `render` to renderers; these primitives ignore it. */
+const noRender = () => null;
+
+/** Narrow a returned node to a property bag for structural assertions. */
+function asRecord(node: unknown): Record<string, unknown> {
+  expect(node).toBeTypeOf('object');
+  return node as Record<string, unknown>;
+}
+
+const ROOT = {
+  Fa: {
+    // Multi-line repeater.
+    FaWiersz: [
+      { P_7: 'Item A', P_11: '100.00' },
+      { P_7: 'Item B', P_11: '200.5' },
+    ],
+    // Single element the parser would collapse into an object (not an array).
+    Solo: { P_7: 'Only', P_11: '5' },
+    P_15: '1234.5',
+  },
+};
+
+const COLS = [
+  { label: 'name', path: 'P_7' },
+  { label: 'amount', path: 'P_11', format: 'money' as const },
+];
+
+describe('tableRenderer', () => {
+  it('renders a repeater with a 2-element array (header + 2 body rows)', () => {
+    const block: TableBlock = { type: 'table', from: 'Fa.FaWiersz', columns: COLS };
+    const node = asRecord(tableRenderer(block, makeCtx(ROOT), noRender));
+    const table = asRecord(node.table);
+    const body = table.body as Record<string, unknown>[][];
+
+    expect(table.headerRows).toBe(1);
+    expect(table.widths).toEqual(['*', '*']);
+    expect(body).toHaveLength(3); // header + 2 rows
+    // Header row uses the (identity) label resolver.
+    expect(body[0]).toEqual([
+      { text: 'name', bold: true },
+      { text: 'amount', bold: true },
+    ]);
+    // Row-relative bindings + formatter application in a cell.
+    expect(body[1][0]).toEqual({ text: 'Item A' });
+    expect(body[1][1]).toEqual({ text: '100,00' });
+    expect(body[2][1]).toEqual({ text: '200,50' });
+    // Light layout, no style when unset.
+    expect(node.layout).toBe('lightHorizontalLines');
+    expect(node.style).toBeUndefined();
+  });
+
+  it('renders a repeater whose single element collapsed to an object (header + 1 row)', () => {
+    const block: TableBlock = { type: 'table', from: 'Fa.Solo', columns: COLS };
+    const node = asRecord(tableRenderer(block, makeCtx(ROOT), noRender));
+    const body = asRecord(node.table).body as Record<string, unknown>[][];
+
+    expect(body).toHaveLength(2); // header + single collapsed row
+    expect(body[1][0]).toEqual({ text: 'Only' });
+    expect(body[1][1]).toEqual({ text: '5,00' });
+  });
+
+  it('renders a single root-relative row when `from` is absent', () => {
+    const block: TableBlock = {
+      type: 'table',
+      columns: [{ label: 'total', path: 'Fa.P_15', format: 'money' }],
+    };
+    const node = asRecord(tableRenderer(block, makeCtx(ROOT), noRender));
+    const body = asRecord(node.table).body as Record<string, unknown>[][];
+
+    expect(body).toHaveLength(2); // header + single root row
+    // Thousands are grouped with a non-breaking space (formatMoney).
+    expect(body[1][0]).toEqual({ text: '1\u00A0234,50' });
+  });
+
+  it('resolves a non-XML binding for a root-relative cell', () => {
+    const block: TableBlock = { type: 'table', columns: [{ label: 'k', path: 'opts.ksefNumber' }] };
+    const ctx = makeCtx(ROOT, { bindings: { 'opts.ksefNumber': 'KSEF-1' } });
+    const node = asRecord(tableRenderer(block, ctx, noRender));
+    const body = asRecord(node.table).body as Record<string, unknown>[][];
+    expect(body[1][0]).toEqual({ text: 'KSEF-1' });
+  });
+
+  it('omits the header row when `headers` is false', () => {
+    const block: TableBlock = { type: 'table', from: 'Fa.FaWiersz', columns: COLS, headers: false };
+    const node = asRecord(tableRenderer(block, makeCtx(ROOT), noRender));
+    const table = asRecord(node.table);
+    const body = table.body as Record<string, unknown>[][];
+
+    expect(table.headerRows).toBe(0);
+    expect(body).toHaveLength(2); // no header, 2 rows only
+    expect(body[0][0]).toEqual({ text: 'Item A' });
+  });
+
+  it('attaches a style when set', () => {
+    const block: TableBlock = { type: 'table', from: 'Fa.FaWiersz', columns: COLS, style: 'lines' };
+    const node = asRecord(tableRenderer(block, makeCtx(ROOT), noRender));
+    expect(node.style).toBe('lines');
+  });
+});
+
+describe('imageRenderer', () => {
+  it('uses a literal `src` data URI with the default width', () => {
+    const block: ImageBlock = { type: 'image', src: 'data:image/png;base64,AAAA' };
+    const node = asRecord(imageRenderer(block, makeCtx(ROOT), noRender));
+    expect(node).toEqual({ image: 'data:image/png;base64,AAAA', width: 120 });
+  });
+
+  it('resolves a `path` binding when `src` is absent', () => {
+    const block: ImageBlock = { type: 'image', path: 'opts.logo', width: 80 };
+    const ctx = makeCtx(ROOT, { bindings: { 'opts.logo': 'data:image/png;base64,BBBB' } });
+    const node = asRecord(imageRenderer(block, ctx, noRender));
+    expect(node).toEqual({ image: 'data:image/png;base64,BBBB', width: 80 });
+  });
+
+  it('honours a custom `width`', () => {
+    const block: ImageBlock = { type: 'image', src: 'data:image/png;base64,CCCC', width: 42 };
+    const node = asRecord(imageRenderer(block, makeCtx(ROOT), noRender));
+    expect(node.width).toBe(42);
+  });
+
+  it('returns an empty text node when the `path` binding resolves empty', () => {
+    const block: ImageBlock = { type: 'image', path: 'opts.logo' };
+    const node = asRecord(imageRenderer(block, makeCtx(ROOT), noRender));
+    expect(node).toEqual({ text: '' });
+  });
+
+  it('returns an empty text node when neither `src` nor `path` is set', () => {
+    const block: ImageBlock = { type: 'image' };
+    const node = asRecord(imageRenderer(block, makeCtx(ROOT), noRender));
+    expect(node).toEqual({ text: '' });
+  });
+});
diff --git a/packages/ksef-client-ts/tests/unit/pdf/blocks-semantic.test.ts b/packages/ksef-client-ts/tests/unit/pdf/blocks-semantic.test.ts
new file mode 100644
index 0000000..444e461
--- /dev/null
+++ b/packages/ksef-client-ts/tests/unit/pdf/blocks-semantic.test.ts
@@ -0,0 +1,383 @@
+/**
+ * Semantic (node-structure) tests for the block renderers. We assert the shape
+ * of the emitted pdfmake nodes — never bytes. Each renderer is exercised through
+ * every branch: present/absent optional style, empty vs populated collections,
+ * collapsed vs expanded repeaters, and strict vs non-strict binding resolution.
+ */
+import { describe, it, expect } from 'vitest';
+import type { RenderContext, RenderChild, PdfNode } from '../../../src/pdf/template/interpret.js';
+import { makeLabelResolver } from '../../../src/pdf/i18n/index.js';
+import { applyFormat } from '../../../src/pdf/format.js';
+import { headerRenderer } from '../../../src/pdf/template/blocks/header.js';
+import { partiesRenderer } from '../../../src/pdf/template/blocks/parties.js';
+import { linesRenderer } from '../../../src/pdf/template/blocks/lines.js';
+import { totalsRenderer } from '../../../src/pdf/template/blocks/totals.js';
+import { paymentRenderer } from '../../../src/pdf/template/blocks/payment.js';
+import { annotationsRenderer } from '../../../src/pdf/template/blocks/annotations.js';
+import { footerRenderer } from '../../../src/pdf/template/blocks/footer.js';
+
+// ── test harness ────────────────────────────────────────────────────────────
+
+/** Build a RenderContext by hand. `label` echoes the key by default. */
+function makeCtx(root: unknown, overrides: Partial<RenderContext> = {}): RenderContext {
+  return {
+    root,
+    strict: false,
+    label: (k: string) => k,
+    bindings: {},
+    flags: {},
+    ...overrides,
+  };
+}
+
+/** The child-render callback is unused by these blocks. */
+const noRender: RenderChild = () => null;
+
+/** Cast a node to an indexable bag for structural assertions. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const rec = (n: PdfNode | PdfNode[] | null): any => n as any;
+
+// ── header (existing renderer) ───────────────────────────────────────────────
+
+describe('headerRenderer', () => {
+  it('renders logo, title, number and date with an explicit style', () => {
+    const ctx = makeCtx(
+      { Fa: { P_2: 'FV/2025/01', P_1: '2025-01-15' } },
+      { bindings: { 'opts.logo': 'data:image/png;base64,AAAA' } },
+    );
+    const node = rec(
+      headerRenderer(
+        {
+          type: 'header',
+          logo: 'opts.logo',
+          title: { label: 'invoice' },
+          number: 'Fa.P_2',
+          date: 'Fa.P_1',
+          style: 'bigtitle',
+        },
+        ctx,
+        noRender,
+      ),
+    );
+
+    expect(node.columns).toHaveLength(2);
+    const [left, right] = node.columns;
+    // logo image + title
+    expect(left.stack[0].image).toBe('data:image/png;base64,AAAA');
+    expect(left.stack[1].text).toBe('invoice');
+    expect(left.stack[1].style).toBe('bigtitle');
+    // number + date, right-aligned
+    expect(right.alignment).toBe('right');
+    expect(right.stack).toHaveLength(2);
+    expect(right.stack[0].text).toBe('invoiceNumber: FV/2025/01');
+    expect(right.stack[1].text).toBe('issueDate: 15.01.2025');
+  });
+
+  it('falls back to the invoice label and default title style, omitting empty right column', () => {
+    const node = rec(headerRenderer({ type: 'header' }, makeCtx({}), noRender));
+    const [left, right] = node.columns;
+    expect(left.stack).toHaveLength(1);
+    expect(left.stack[0].text).toBe('invoice'); // label('invoice')
+    expect(left.stack[0].style).toBe('title'); // default
+    expect(right.stack).toHaveLength(0);
+  });
+
+  it('drops the logo node when its binding resolves empty', () => {
+    const node = rec(headerRenderer({ type: 'header', logo: 'missing.logo' }, makeCtx({}), noRender));
+    const [left] = node.columns;
+    // no image pushed; only the title line remains
+    expect(left.stack).toHaveLength(1);
+    expect(left.stack[0].image).toBeUndefined();
+  });
+});
+
+// ── parties ───────────────────────────────────────────────────────────────
+
+describe('partiesRenderer', () => {
+  it('emits a two-column layout with a bold label line and one line per field', () => {
+    const ctx = makeCtx({
+      Podmiot1: { Nazwa: 'ACME Sp. z o.o.', NIP: '5213003700' },
+      Podmiot2: { Nazwa: 'Buyer Co' },
+    });
+    const node = rec(
+      partiesRenderer(
+        {
+          type: 'parties',
+          left: { label: 'seller', fields: ['Podmiot1.Nazwa', 'Podmiot1.NIP'] },
+          right: { label: 'buyer', fields: ['Podmiot2.Nazwa'] },
+          style: 'pstyle',
+        },
+        ctx,
+        noRender,
+      ),
+    );
+
+    expect(node.columns).toHaveLength(2);
+    expect(node.style).toBe('pstyle');
+
+    const [left, right] = node.columns;
+    expect(left.width).toBe('*');
+    expect(left.stack).toHaveLength(3); // label + 2 fields
+    expect(left.stack[0].text).toBe('seller');
+    expect(left.stack[0].style).toBe('h2');
+    expect(left.stack[1].text).toBe('ACME Sp. z o.o.');
+    expect(left.stack[2].text).toBe('5213003700');
+
+    expect(right.stack).toHaveLength(2); // label + 1 field
+    expect(right.stack[1].text).toBe('Buyer Co');
+  });
+
+  it('handles empty field lists and omits style when absent', () => {
+    const node = rec(
+      partiesRenderer(
+        {
+          type: 'parties',
+          left: { label: 'seller', fields: [] },
+          right: { label: 'buyer', fields: [] },
+        },
+        makeCtx({}),
+        noRender,
+      ),
+    );
+    expect(node.style).toBeUndefined();
+    expect('style' in node).toBe(false);
+    expect(node.columns[0].stack).toHaveLength(1); // label only
+  });
+
+  it('resolves real localized labels via makeLabelResolver', () => {
+    const ctx = makeCtx({ Podmiot1: { Nazwa: 'X' } }, { label: makeLabelResolver('pl') });
+    const node = rec(
+      partiesRenderer(
+        {
+          type: 'parties',
+          left: { label: 'seller', fields: ['Podmiot1.Nazwa'] },
+          right: { label: 'buyer', fields: [] },
+        },
+        ctx,
+        noRender,
+      ),
+    );
+    expect(node.columns[0].stack[0].text).toBe('Sprzedawca');
+    expect(node.columns[1].stack[0].text).toBe('Nabywca');
+  });
+});
+
+// ── lines ─────────────────────────────────────────────────────────────────
+
+const lineColumns = [
+  { label: 'lp', path: 'NrWierszaFa' },
+  { label: 'name', path: 'P_7' },
+  { label: 'qty', path: 'P_8B', format: 'number' as const },
+  { label: 'net', path: 'P_9A', format: 'money' as const },
+];
+
+describe('linesRenderer', () => {
+  it('renders a header row plus one body row for a collapsed single line', () => {
+    const ctx = makeCtx({
+      Fa: { FaWiersz: { NrWierszaFa: '1', P_7: 'Widget', P_8B: '2', P_9A: '10.00' } },
+    });
+    const node = rec(
+      linesRenderer({ type: 'lines', from: 'Fa.FaWiersz', columns: lineColumns }, ctx, noRender),
+    );
+
+    expect(node.table.headerRows).toBe(1);
+    expect(node.table.widths).toHaveLength(4);
+    expect(node.layout).toBe('lightHorizontalLines');
+    expect(node.table.body).toHaveLength(2); // 1 header + 1 line
+
+    // header cells echo the column labels and are bold
+    const header = node.table.body[0];
+    expect(header.map((c: any) => c.text)).toEqual(['lp', 'name', 'qty', 'net']);
+    expect(header.every((c: any) => c.bold === true)).toBe(true);
+
+    // body cell values are formatted
+    const row = node.table.body[1];
+    expect(row[0].text).toBe('1');
+    expect(row[1].text).toBe('Widget');
+    expect(row[2].text).toBe(applyFormat('2', 'number'));
+    expect(row[3].text).toBe(applyFormat('10.00', 'money')); // '10,00'
+    expect(node.style).toBeUndefined();
+  });
+
+  it('renders one body row per element for an expanded array of lines (+ style)', () => {
+    const ctx = makeCtx({ Fa: { FaWiersz: [{ P_7: 'A' }, { P_7: 'B' }] } });
+    const node = rec(
+      linesRenderer(
+        {
+          type: 'lines',
+          from: 'Fa.FaWiersz',
+          columns: [
+            { label: 'name', path: 'P_7' },
+            { label: 'qty', path: 'P_8B' }, // missing → '' (non-strict)
+          ],
+          style: 'lstyle',
+        },
+        ctx,
+        noRender,
+      ),
+    );
+    expect(node.table.body).toHaveLength(3); // 1 header + 2 lines
+    expect(node.table.body[1][0].text).toBe('A');
+    expect(node.table.body[2][0].text).toBe('B');
+    expect(node.table.body[1][1].text).toBe(''); // missing binding, non-strict
+    expect(node.style).toBe('lstyle');
+  });
+
+  it('emits only the header row for an empty collection', () => {
+    const node = rec(
+      linesRenderer({ type: 'lines', from: 'Fa.FaWiersz', columns: lineColumns }, makeCtx({ Fa: {} }), noRender),
+    );
+    expect(node.table.body).toHaveLength(1); // header only
+  });
+
+  it('throws in strict mode on a missing cell binding', () => {
+    const ctx = makeCtx({ Fa: { FaWiersz: { P_7: 'X' } } }, { strict: true });
+    expect(() =>
+      linesRenderer(
+        { type: 'lines', from: 'Fa.FaWiersz', columns: [{ label: 'name', path: 'P_MISSING' }] },
+        ctx,
+        noRender,
+      ),
+    ).toThrow(/Missing binding/);
+  });
+});
+
+// ── totals ──────────────────────────────────────────────────────────────────
+
+describe('totalsRenderer', () => {
+  it('renders a right-aligned borderless summary table (+ style)', () => {
+    const ctx = makeCtx({ Fa: { P_13_1: '100', P_15: '123' } });
+    const node = rec(
+      totalsRenderer(
+        {
+          type: 'totals',
+          rows: [
+            { label: 'totalNet', path: 'Fa.P_13_1', format: 'money' },
+            { label: 'totalDue', path: 'Fa.P_15', format: 'money' },
+          ],
+          style: 'tstyle',
+        },
+        ctx,
+        noRender,
+      ),
+    );
+
+    expect(node.columns).toHaveLength(2);
+    expect(node.columns[0].text).toBe(''); // elastic spacer
+    expect(node.columns[0].width).toBe('*');
+    expect(node.style).toBe('tstyle');
+
+    const summary = node.columns[1];
+    expect(summary.layout).toBe('noBorders');
+    expect(summary.table.body).toHaveLength(2);
+    const [labelCell, valueCell] = summary.table.body[0];
+    expect(labelCell.text).toBe('totalNet');
+    expect(labelCell.bold).toBe(true);
+    expect(valueCell.text).toBe(applyFormat('100', 'money')); // '100,00'
+    expect(valueCell.alignment).toBe('right');
+  });
+
+  it('omits style when absent', () => {
+    const node = rec(
+      totalsRenderer({ type: 'totals', rows: [{ label: 'totalDue', path: 'Fa.P_15' }] }, makeCtx({ Fa: { P_15: '5' } }), noRender),
+    );
+    expect('style' in node).toBe(false);
+    expect(node.columns[1].table.body).toHaveLength(1);
+  });
+});
+
+// ── payment ───────────────────────────────────────────────────────────────
+
+describe('paymentRenderer', () => {
+  it('renders a heading and one label:value line per row (+ style)', () => {
+    const ctx = makeCtx({
+      Fa: { FormaPlatnosci: '6', TerminPlatnosci: { Termin: '2025-02-01' } },
+    });
+    const node = rec(
+      paymentRenderer(
+        {
+          type: 'payment',
+          rows: [
+            { label: 'paymentMethod', path: 'Fa.FormaPlatnosci' },
+            { label: 'paymentDate', path: 'Fa.TerminPlatnosci.Termin', format: 'date' },
+          ],
+          style: 'paystyle',
+        },
+        ctx,
+        noRender,
+      ),
+    );
+
+    expect(node.stack).toHaveLength(3); // heading + 2 rows
+    expect(node.stack[0].text).toBe('payment');
+    expect(node.stack[0].style).toBe('h2');
+    expect(node.stack[1].text).toBe('paymentMethod: 6');
+    expect(node.stack[2].text).toBe('paymentDate: 01.02.2025');
+    expect(node.style).toBe('paystyle');
+  });
+
+  it('renders only the heading for no rows and omits style', () => {
+    const node = rec(paymentRenderer({ type: 'payment', rows: [] }, makeCtx({}), noRender));
+    expect(node.stack).toHaveLength(1);
+    expect(node.stack[0].text).toBe('payment');
+    expect('style' in node).toBe(false);
+  });
+});
+
+// ── annotations ─────────────────────────────────────────────────────────────
+
+describe('annotationsRenderer', () => {
+  it('renders a heading and one label:value line per field (+ style)', () => {
+    const ctx = makeCtx({ Fa: { Adnotacje: { P_16: '1', P_17: '2' } } });
+    const node = rec(
+      annotationsRenderer(
+        {
+          type: 'annotations',
+          fields: [
+            { label: 'annotations', path: 'Fa.Adnotacje.P_16' },
+            { label: 'annotations', path: 'Fa.Adnotacje.P_17' },
+          ],
+          style: 'astyle',
+        },
+        ctx,
+        noRender,
+      ),
+    );
+    expect(node.stack).toHaveLength(3); // heading + 2 fields
+    expect(node.stack[0].text).toBe('annotations');
+    expect(node.stack[1].text).toBe('annotations: 1');
+    expect(node.stack[2].text).toBe('annotations: 2');
+    expect(node.style).toBe('astyle');
+  });
+
+  it('renders only the heading for no fields and omits style', () => {
+    const node = rec(annotationsRenderer({ type: 'annotations', fields: [] }, makeCtx({}), noRender));
+    expect(node.stack).toHaveLength(1);
+    expect('style' in node).toBe(false);
+  });
+});
+
+// ── footer ────────────────────────────────────────────────────────────────
+
+describe('footerRenderer', () => {
+  it('renders a centered label-resolved line', () => {
+    const node = rec(footerRenderer({ type: 'footer', label: 'page' }, makeCtx({}), noRender));
+    expect(node.text).toBe('page');
+    expect(node.alignment).toBe('center');
+    expect('style' in node).toBe(false);
+  });
+
+  it('renders literal text with a style', () => {
+    const node = rec(
+      footerRenderer({ type: 'footer', text: 'Thank you', style: 'fstyle' }, makeCtx({}), noRender),
+    );
+    expect(node.text).toBe('Thank you');
+    expect(node.style).toBe('fstyle');
+  });
+
+  it('renders an empty string when neither label nor text is set', () => {
+    const node = rec(footerRenderer({ type: 'footer' }, makeCtx({}), noRender));
+    expect(node.text).toBe('');
+    expect(node.alignment).toBe('center');
+  });
+});
diff --git a/packages/ksef-client-ts/tests/unit/pdf/dsl.test.ts b/packages/ksef-client-ts/tests/unit/pdf/dsl.test.ts
new file mode 100644
index 0000000..da15ad4
--- /dev/null
+++ b/packages/ksef-client-ts/tests/unit/pdf/dsl.test.ts
@@ -0,0 +1,138 @@
+import { describe, it, expect } from 'vitest';
+import { validateTemplate } from '../../../src/pdf/template/dsl.js';
+import type { InvoiceTemplate } from '../../../src/pdf/template/dsl.js';
+import { KSeFValidationError } from '../../../src/errors/ksef-validation-error.js';
+
+/** A small but structurally rich valid template (header + text + nested container). */
+const VALID: unknown = {
+  schema: 'FA(3)',
+  page: { size: 'A4', orientation: 'portrait', margins: [40, 40, 40, 40] },
+  defaultStyle: { fontSize: 9 },
+  styles: { h1: { fontSize: 14, bold: true } },
+  labels: { seller: 'Wystawca' },
+  blocks: [
+    { type: 'header', title: { label: 'invoice' }, number: 'Fa.P_2', style: 'h1' },
+    { type: 'text', text: 'Hello', style: 'h1' },
+    {
+      type: 'columns',
+      columns: [
+        { type: 'text', path: 'Fa.P_1', format: 'date' },
+        {
+          type: 'stack',
+          stack: [
+            { type: 'text', label: 'seller' },
+            { type: 'divider' },
+          ],
+        },
+      ],
+    },
+  ],
+};
+
+describe('validateTemplate', () => {
+  it('returns the typed template for a valid input', () => {
+    const template: InvoiceTemplate = validateTemplate(VALID);
+    expect(template.schema).toBe('FA(3)');
+    expect(template.blocks).toHaveLength(3);
+    expect(template.blocks[0].type).toBe('header');
+    // The recursive container is preserved through validation.
+    const cols = template.blocks[2];
+    expect(cols.type).toBe('columns');
+  });
+
+  it('validates a deeply nested container (columns → stack → blocks)', () => {
+    const nested: unknown = {
+      schema: 'FA(2)',
+      blocks: [
+        {
+          type: 'stack',
+          stack: [
+            {
+              type: 'columns',
+              columns: [{ type: 'text', text: 'a' }, { type: 'spacer', height: 4 }],
+            },
+          ],
+        },
+      ],
+    };
+    expect(() => validateTemplate(nested)).not.toThrow();
+  });
+
+  it('throws KSeFValidationError for an unknown block type', () => {
+    expect(() => validateTemplate({ schema: 'FA(3)', blocks: [{ type: 'bogus' }] })).toThrow(
+      KSeFValidationError,
+    );
+  });
+
+  it("includes a path segment for an unknown block type", () => {
+    try {
+      validateTemplate({ schema: 'FA(3)', blocks: [{ type: 'bogus' }] });
+      expect.unreachable('expected validateTemplate to throw');
+    } catch (e) {
+      expect(e).toBeInstanceOf(KSeFValidationError);
+      expect((e as Error).message).toContain('blocks.0.type');
+    }
+  });
+
+  it('throws for an extra/unknown key on a block (strict schema)', () => {
+    try {
+      validateTemplate({ schema: 'FA(3)', blocks: [{ type: 'text', text: 'x', bogus: 1 }] });
+      expect.unreachable('expected validateTemplate to throw');
+    } catch (e) {
+      expect(e).toBeInstanceOf(KSeFValidationError);
+      expect((e as Error).message).toContain('blocks.0');
+      expect((e as Error).message).toContain('bogus');
+    }
+  });
+
+  it('throws for an extra/unknown key on the root (strict schema)', () => {
+    try {
+      validateTemplate({ schema: 'FA(3)', blocks: [], bogus: 1 });
+      expect.unreachable('expected validateTemplate to throw');
+    } catch (e) {
+      expect(e).toBeInstanceOf(KSeFValidationError);
+      expect((e as Error).message).toContain('(root)');
+    }
+  });
+
+  it('throws for a missing required block field (lines without from)', () => {
+    try {
+      validateTemplate({ schema: 'FA(3)', blocks: [{ type: 'lines', columns: [] }] });
+      expect.unreachable('expected validateTemplate to throw');
+    } catch (e) {
+      expect(e).toBeInstanceOf(KSeFValidationError);
+      expect((e as Error).message).toContain('blocks.0.from');
+    }
+  });
+
+  it('throws when the root omits blocks', () => {
+    try {
+      validateTemplate({ schema: 'FA(3)' });
+      expect.unreachable('expected validateTemplate to throw');
+    } catch (e) {
+      expect(e).toBeInstanceOf(KSeFValidationError);
+      expect((e as Error).message).toContain('blocks');
+    }
+  });
+
+  it('throws for an invalid schema id', () => {
+    try {
+      validateTemplate({ schema: 'ZZ', blocks: [] });
+      expect.unreachable('expected validateTemplate to throw');
+    } catch (e) {
+      expect(e).toBeInstanceOf(KSeFValidationError);
+      expect((e as Error).message).toContain('schema');
+    }
+  });
+
+  it('exposes each issue as a details entry', () => {
+    try {
+      validateTemplate({ schema: 'FA(3)', blocks: [{ type: 'lines', columns: [] }] });
+      expect.unreachable('expected validateTemplate to throw');
+    } catch (e) {
+      const err = e as KSeFValidationError;
+      expect(err.details.length).toBeGreaterThan(0);
+      expect(err.details[0].message).toContain('blocks.0.from');
+    }
+  });
+});
diff --git a/packages/ksef-client-ts/tests/unit/pdf/errors.test.ts b/packages/ksef-client-ts/tests/unit/pdf/errors.test.ts
new file mode 100644
index 0000000..60b8fee
--- /dev/null
+++ b/packages/ksef-client-ts/tests/unit/pdf/errors.test.ts
@@ -0,0 +1,20 @@
+import { describe, it, expect } from 'vitest';
+import { KSeFPdfError } from '../../../src/pdf/errors.js';
+import { KSeFError } from '../../../src/errors/ksef-error.js';
+
+describe('KSeFPdfError', () => {
+  it('is an instance of KSeFError and Error', () => {
+    const err = new KSeFPdfError('boom');
+    expect(err).toBeInstanceOf(KSeFPdfError);
+    expect(err).toBeInstanceOf(KSeFError);
+    expect(err).toBeInstanceOf(Error);
+  });
+
+  it('sets its name to KSeFPdfError', () => {
+    expect(new KSeFPdfError('x').name).toBe('KSeFPdfError');
+  });
+
+  it('preserves the message', () => {
+    expect(new KSeFPdfError('missing pdfmake').message).toBe('missing pdfmake');
+  });
+});
diff --git a/packages/ksef-client-ts/tests/unit/pdf/fonts-loader.test.ts b/packages/ksef-client-ts/tests/unit/pdf/fonts-loader.test.ts
new file mode 100644
index 0000000..ad01063
--- /dev/null
+++ b/packages/ksef-client-ts/tests/unit/pdf/fonts-loader.test.ts
@@ -0,0 +1,37 @@
+import { describe, it, expect, vi } from 'vitest';
+import { assertPdfmakeVersion, loadPdfMake } from '../../../src/pdf/fonts.js';
+import { KSeFPdfError } from '../../../src/pdf/errors.js';
+
+// Simulate "pdfmake not installed": the dynamic import inside loadPdfMake fails.
+// The version reader (createRequire on the real package.json) is unaffected, so
+// this exercises the import-catch → friendly-error branch specifically.
+vi.mock('pdfmake/build/pdfmake.js', () => {
+  throw new Error('mock: module not found');
+});
+
+describe('assertPdfmakeVersion', () => {
+  it('throws a friendly install error when pdfmake is absent (null version)', () => {
+    expect(() => assertPdfmakeVersion(null)).toThrow(KSeFPdfError);
+    expect(() => assertPdfmakeVersion(null)).toThrow(/npm i "pdfmake\^?0?\.?2?\.?20?"|pdfmake@\^0\.2\.20/);
+  });
+
+  it('rejects an incompatible 0.3.x version with a clear message', () => {
+    expect(() => assertPdfmakeVersion('0.3.11')).toThrow(/0\.3\.x is not supported|found 0\.3\.11/);
+  });
+
+  it('rejects a too-old 0.2.x version', () => {
+    expect(() => assertPdfmakeVersion('0.2.19')).toThrow(KSeFPdfError);
+  });
+
+  it('accepts a supported version', () => {
+    expect(() => assertPdfmakeVersion('0.2.20')).not.toThrow();
+    expect(() => assertPdfmakeVersion('0.2.99')).not.toThrow();
+  });
+});
+
+describe('loadPdfMake — friendly error when pdfmake import fails', () => {
+  it('throws KSeFPdfError with an install hint instead of a raw resolver crash', async () => {
+    await expect(loadPdfMake()).rejects.toBeInstanceOf(KSeFPdfError);
+    await expect(loadPdfMake()).rejects.toThrow(/pdfmake/);
+  });
+});
diff --git a/packages/ksef-client-ts/tests/unit/pdf/fonts.test.ts b/packages/ksef-client-ts/tests/unit/pdf/fonts.test.ts
new file mode 100644
index 0000000..483ccf6
--- /dev/null
+++ b/packages/ksef-client-ts/tests/unit/pdf/fonts.test.ts
@@ -0,0 +1,65 @@
+import { describe, it, expect } from 'vitest';
+import { satisfiesRequiredRange, normalizeVfs } from '../../../src/pdf/fonts.js';
+
+describe('satisfiesRequiredRange', () => {
+  it('accepts the exact lower bound 0.2.20', () => {
+    expect(satisfiesRequiredRange('0.2.20')).toBe(true);
+  });
+
+  it('accepts a higher patch within 0.2.x', () => {
+    expect(satisfiesRequiredRange('0.2.99')).toBe(true);
+  });
+
+  it('rejects a patch below 20', () => {
+    expect(satisfiesRequiredRange('0.2.19')).toBe(false);
+  });
+
+  it('rejects the 0.3.0 minor bump', () => {
+    expect(satisfiesRequiredRange('0.3.0')).toBe(false);
+  });
+
+  it('rejects any 0.3.x', () => {
+    expect(satisfiesRequiredRange('0.3.11')).toBe(false);
+  });
+
+  it('rejects an older minor', () => {
+    expect(satisfiesRequiredRange('0.1.5')).toBe(false);
+  });
+
+  it('rejects a major bump', () => {
+    expect(satisfiesRequiredRange('1.0.0')).toBe(false);
+  });
+
+  it('rejects a non-semver string', () => {
+    expect(satisfiesRequiredRange('abc')).toBe(false);
+  });
+
+  it('rejects an empty string', () => {
+    expect(satisfiesRequiredRange('')).toBe(false);
+  });
+});
+
+describe('normalizeVfs', () => {
+  // A font map never carries `vfs`/`default`/`pdfMake` keys of its own.
+  const fontMap = { 'Roboto-Regular.ttf': 'AAAA', 'Roboto-Bold.ttf': 'BBBB' };
+
+  it('unwraps { default: <map> } (ESM default export that is the map itself)', () => {
+    expect(normalizeVfs({ default: fontMap })).toBe(fontMap);
+  });
+
+  it('unwraps { default: { vfs: <map> } }', () => {
+    expect(normalizeVfs({ default: { vfs: fontMap } })).toBe(fontMap);
+  });
+
+  it('unwraps { vfs: <map> }', () => {
+    expect(normalizeVfs({ vfs: fontMap })).toBe(fontMap);
+  });
+
+  it('unwraps { pdfMake: { vfs: <map> } }', () => {
+    expect(normalizeVfs({ pdfMake: { vfs: fontMap } })).toBe(fontMap);
+  });
+
+  it('returns a bare map unchanged', () => {
+    expect(normalizeVfs(fontMap)).toBe(fontMap);
+  });
+});
diff --git a/packages/ksef-client-ts/tests/unit/pdf/format.test.ts b/packages/ksef-client-ts/tests/unit/pdf/format.test.ts
new file mode 100644
index 0000000..1c8f7e3
--- /dev/null
+++ b/packages/ksef-client-ts/tests/unit/pdf/format.test.ts
@@ -0,0 +1,117 @@
+import { describe, it, expect } from 'vitest';
+import {
+  formatMoney,
+  formatNumber,
+  formatDate,
+  formatNip,
+  applyFormat,
+} from '../../../src/pdf/format.js';
+
+/**
+ * The thousands separator is a non-breaking space (U+00A0), NOT an ASCII space.
+ * Spelled as an escape so the assertions are unambiguous.
+ */
+const NBSP = ' ';
+
+describe('formatMoney', () => {
+  it('groups thousands with a non-breaking space and forces 2 decimals', () => {
+    expect(formatMoney('1234.5')).toBe(`1${NBSP}234,50`);
+  });
+
+  it('formats a value below 1000 without a group separator', () => {
+    expect(formatMoney('12.3')).toBe('12,30');
+  });
+
+  it('groups multiple thousands groups', () => {
+    expect(formatMoney('1234567.8')).toBe(`1${NBSP}234${NBSP}567,80`);
+  });
+
+  it('preserves a negative sign in front of the grouped value', () => {
+    expect(formatMoney('-1234.5')).toBe(`-1${NBSP}234,50`);
+  });
+
+  it('passes a non-numeric string through unchanged', () => {
+    expect(formatMoney('abc')).toBe('abc');
+  });
+
+  it('returns an empty string unchanged', () => {
+    expect(formatMoney('')).toBe('');
+  });
+
+  it('returns a whitespace-only string unchanged', () => {
+    expect(formatMoney('   ')).toBe('   ');
+  });
+});
+
+describe('formatNumber', () => {
+  it('groups thousands but does not force decimals', () => {
+    expect(formatNumber('1234.5')).toBe(`1${NBSP}234,5`);
+  });
+
+  it('omits the decimal part for an integer', () => {
+    expect(formatNumber('1000')).toBe(`1${NBSP}000`);
+  });
+
+  it('preserves a negative sign', () => {
+    expect(formatNumber('-1234.5')).toBe(`-1${NBSP}234,5`);
+  });
+
+  it('passes a non-numeric string through unchanged', () => {
+    expect(formatNumber('abc')).toBe('abc');
+  });
+
+  it('returns an empty string unchanged', () => {
+    expect(formatNumber('')).toBe('');
+  });
+});
+
+describe('formatDate', () => {
+  it('reformats an ISO date to DD.MM.YYYY', () => {
+    expect(formatDate('2025-01-15')).toBe('15.01.2025');
+  });
+
+  it('reformats the date portion of a datetime', () => {
+    expect(formatDate('2025-01-15T10:00:00Z')).toBe('15.01.2025');
+  });
+
+  it('passes a non-date string through unchanged', () => {
+    expect(formatDate('not a date')).toBe('not a date');
+  });
+});
+
+describe('formatNip', () => {
+  it('inserts group separators into a 10-digit NIP', () => {
+    expect(formatNip('5213003700')).toBe('521-300-37-00');
+  });
+
+  it('passes a wrong-length value through unchanged', () => {
+    expect(formatNip('123')).toBe('123');
+  });
+});
+
+describe('applyFormat', () => {
+  it('returns the value unchanged when no formatter is named', () => {
+    expect(applyFormat('1234.5', undefined)).toBe('1234.5');
+  });
+
+  it('returns the value unchanged for an unknown formatter name', () => {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    expect(applyFormat('1234.5', 'bogus' as any)).toBe('1234.5');
+  });
+
+  it('routes to the money formatter', () => {
+    expect(applyFormat('1234.5', 'money')).toBe(`1${NBSP}234,50`);
+  });
+
+  it('routes to the number formatter', () => {
+    expect(applyFormat('1234.5', 'number')).toBe(`1${NBSP}234,5`);
+  });
+
+  it('routes to the date formatter', () => {
+    expect(applyFormat('2025-01-15', 'date')).toBe('15.01.2025');
+  });
+
+  it('routes to the nip formatter', () => {
+    expect(applyFormat('5213003700', 'nip')).toBe('521-300-37-00');
+  });
+});
diff --git a/packages/ksef-client-ts/tests/unit/pdf/i18n.test.ts b/packages/ksef-client-ts/tests/unit/pdf/i18n.test.ts
new file mode 100644
index 0000000..a04bb46
--- /dev/null
+++ b/packages/ksef-client-ts/tests/unit/pdf/i18n.test.ts
@@ -0,0 +1,64 @@
+import { describe, it, expect } from 'vitest';
+import { resolveLabel, makeLabelResolver } from '../../../src/pdf/i18n/index.js';
+
+describe('resolveLabel', () => {
+  it('resolves a Polish label from the pl bundle', () => {
+    expect(resolveLabel('seller', 'pl')).toBe('Sprzedawca');
+  });
+
+  it('resolves an English label from the en bundle', () => {
+    expect(resolveLabel('seller', 'en')).toBe('Seller');
+  });
+
+  it('joins pl and en with the default " / " separator for pl+en', () => {
+    expect(resolveLabel('seller', 'pl+en')).toBe('Sprzedawca / Seller');
+  });
+
+  it('honours a custom bilingual separator', () => {
+    expect(resolveLabel('seller', 'pl+en', { bilingualSeparator: '\n' })).toBe(
+      'Sprzedawca\nSeller',
+    );
+  });
+
+  it('lets an override win over the bundle (pl)', () => {
+    expect(resolveLabel('seller', 'pl', { overrides: { seller: 'Wystawca' } })).toBe('Wystawca');
+  });
+
+  it('lets an override win over the bundle (en)', () => {
+    expect(resolveLabel('seller', 'en', { overrides: { seller: 'Vendor' } })).toBe('Vendor');
+  });
+
+  it('applies overrides to both halves of a bilingual label', () => {
+    expect(
+      resolveLabel('seller', 'pl+en', { overrides: { seller: 'X' } }),
+    ).toBe('X / X');
+  });
+
+  it('falls back to the raw key when the key is unknown in every bundle', () => {
+    expect(resolveLabel('totally-unknown-key', 'en')).toBe('totally-unknown-key');
+  });
+
+  it('falls back to the raw key for a bilingual unknown key on both sides', () => {
+    expect(resolveLabel('totally-unknown-key', 'pl+en')).toBe(
+      'totally-unknown-key / totally-unknown-key',
+    );
+  });
+});
+
+describe('makeLabelResolver', () => {
+  it('returns a bound resolver capturing the locale', () => {
+    const resolve = makeLabelResolver('en');
+    expect(resolve('buyer')).toBe('Buyer');
+    expect(resolve('seller')).toBe('Seller');
+  });
+
+  it('captures bilingual options in the bound resolver', () => {
+    const resolve = makeLabelResolver('pl+en', { bilingualSeparator: ' | ' });
+    expect(resolve('buyer')).toBe('Nabywca | Buyer');
+  });
+
+  it('captures overrides in the bound resolver', () => {
+    const resolve = makeLabelResolver('pl', { overrides: { buyer: 'Klient' } });
+    expect(resolve('buyer')).toBe('Klient');
+  });
+});
diff --git a/packages/ksef-client-ts/tests/unit/pdf/interpret.test.ts b/packages/ksef-client-ts/tests/unit/pdf/interpret.test.ts
new file mode 100644
index 0000000..5bb1c36
--- /dev/null
+++ b/packages/ksef-client-ts/tests/unit/pdf/interpret.test.ts
@@ -0,0 +1,336 @@
+import { describe, it, expect } from 'vitest';
+import {
+  resolveBinding,
+  evalWhen,
+  resolveText,
+  interpretBlock,
+  interpretTemplate,
+  coreRegistry,
+  MAX_DEPTH,
+  type RenderContext,
+  type BlockRegistry,
+  type PdfNode,
+} from '../../../src/pdf/template/interpret.js';
+import { KSeFPdfError } from '../../../src/pdf/errors.js';
+import type { Block, InvoiceTemplate } from '../../../src/pdf/template/dsl.js';
+
+/** Build a RenderContext by hand; label is identity so keys pass through. */
+function makeCtx(root: unknown, overrides: Partial<RenderContext> = {}): RenderContext {
+  return {
+    root,
+    strict: false,
+    label: (k: string) => k,
+    bindings: {},
+    flags: {},
+    ...overrides,
+  };
+}
+
+/** Non-breaking space (U+00A0): the thousands separator emitted by formatMoney. */
+const NBSP = String.fromCharCode(0x00a0);
+
+const ROOT = {
+  Fa: {
+    P_1: '2025-01-15',
+    P_2: 'FV/1/2025',
+    P_15: '1234.5',
+    Adnotacje: 'note',
+  },
+};
+
+/** Narrow a returned node to a property bag for structural assertions. */
+function asRecord(node: PdfNode | null): Record<string, unknown> {
+  expect(node).toBeTypeOf('object');
+  expect(node).not.toBeNull();
+  return node as Record<string, unknown>;
+}
+
+// ── resolveBinding ──────────────────────────────────────────────────────────
+
+describe('resolveBinding', () => {
+  it('reads a non-XML binding by exact key before XML', () => {
+    const ctx = makeCtx(ROOT, { bindings: { 'opts.logo': 'data:image/png;base64,AAAA' } });
+    expect(resolveBinding('opts.logo', ctx)).toBe('data:image/png;base64,AAAA');
+  });
+
+  it('falls through to an XML dot-path when the key is not a binding', () => {
+    expect(resolveBinding('Fa.P_2', makeCtx(ROOT))).toBe('FV/1/2025');
+  });
+
+  it('yields "" for a missing XML path in non-strict mode', () => {
+    expect(resolveBinding('Fa.DoesNotExist', makeCtx(ROOT))).toBe('');
+  });
+
+  it('propagates a strict-mode throw for a missing XML path', () => {
+    const ctx = makeCtx(ROOT, { strict: true });
+    expect(() => resolveBinding('Fa.DoesNotExist', ctx)).toThrow(/Missing binding/);
+  });
+
+  it('does not apply strict mode to a resolved non-XML binding', () => {
+    const ctx = makeCtx(ROOT, { strict: true, bindings: { hash: 'abc' } });
+    expect(resolveBinding('hash', ctx)).toBe('abc');
+  });
+
+  it('coerces an undefined binding value to ""', () => {
+    // The key is present but maps to undefined at runtime (defensive `?? ""`).
+    const ctx = makeCtx(ROOT, { bindings: { hash: undefined as unknown as string } });
+    expect(resolveBinding('hash', ctx)).toBe('');
+  });
+});
+
+// ── evalWhen ────────────────────────────────────────────────────────────────
+
+describe('evalWhen', () => {
+  it('treats an undefined condition as visible', () => {
+    expect(evalWhen(undefined, makeCtx(ROOT))).toBe(true);
+  });
+
+  it('reads a boolean flag when the key is a flag', () => {
+    expect(evalWhen('qr', makeCtx(ROOT, { flags: { qr: true } }))).toBe(true);
+    expect(evalWhen('qr', makeCtx(ROOT, { flags: { qr: false } }))).toBe(false);
+  });
+
+  it('treats a non-empty binding key as visible and an empty one as hidden', () => {
+    expect(evalWhen('opts.ksefNumber', makeCtx(ROOT, { bindings: { 'opts.ksefNumber': 'KSEF-1' } }))).toBe(true);
+    expect(evalWhen('opts.ksefNumber', makeCtx(ROOT, { bindings: { 'opts.ksefNumber': '' } }))).toBe(false);
+  });
+
+  it('falls back to an XML presence test when the key is neither flag nor binding', () => {
+    expect(evalWhen('Fa.P_2', makeCtx(ROOT))).toBe(true);
+    expect(evalWhen('Fa.Missing', makeCtx(ROOT))).toBe(false);
+  });
+
+  it('prefers a flag over a same-named binding', () => {
+    const ctx = makeCtx(ROOT, { flags: { dup: false }, bindings: { dup: 'present' } });
+    expect(evalWhen('dup', ctx)).toBe(false);
+  });
+
+  it('treats a binding key mapping to undefined as hidden (defensive `?? ""`)', () => {
+    const ctx = makeCtx(ROOT, { bindings: { maybe: undefined as unknown as string } });
+    expect(evalWhen('maybe', ctx)).toBe(false);
+  });
+});
+
+// ── resolveText ─────────────────────────────────────────────────────────────
+
+describe('resolveText', () => {
+  it('resolves a { label } ref through the label resolver', () => {
+    expect(resolveText({ label: 'seller' }, makeCtx(ROOT))).toBe('seller');
+  });
+
+  it('returns a { text } literal verbatim', () => {
+    expect(resolveText({ text: 'Literal' }, makeCtx(ROOT))).toBe('Literal');
+  });
+
+  it('resolves a { path } binding and applies the formatter', () => {
+    expect(resolveText({ path: 'Fa.P_1', format: 'date' }, makeCtx(ROOT))).toBe('15.01.2025');
+  });
+
+  it('resolves a { path } binding unformatted when no format is given', () => {
+    expect(resolveText({ path: 'Fa.P_2' }, makeCtx(ROOT))).toBe('FV/1/2025');
+  });
+
+  it('returns "" for an undefined spec', () => {
+    expect(resolveText(undefined, makeCtx(ROOT))).toBe('');
+  });
+
+  it('returns "" for an empty spec (no label/text/path)', () => {
+    expect(resolveText({}, makeCtx(ROOT))).toBe('');
+  });
+});
+
+// ── interpretBlock: primitives + control ────────────────────────────────────
+
+describe('interpretBlock core primitives', () => {
+  it('renders a text block', () => {
+    const node = asRecord(interpretBlock({ type: 'text', text: 'Hello' }, makeCtx(ROOT), coreRegistry, 0));
+    expect(node).toEqual({ text: 'Hello' });
+  });
+
+  it('attaches a style to a text block', () => {
+    const node = asRecord(
+      interpretBlock({ type: 'text', text: 'Hello', style: 'h1' }, makeCtx(ROOT), coreRegistry, 0),
+    );
+    expect(node).toEqual({ text: 'Hello', style: 'h1' });
+  });
+
+  it('renders a text block from a formatted path binding', () => {
+    const block: Block = { type: 'text', path: 'Fa.P_15', format: 'money' };
+    const node = asRecord(interpretBlock(block, makeCtx(ROOT), coreRegistry, 0));
+    expect(node).toEqual({ text: `1${NBSP}234,50` });
+  });
+
+  it('renders a stack, flattening and dropping hidden children', () => {
+    const block: Block = {
+      type: 'stack',
+      stack: [
+        { type: 'text', text: 'a' },
+        { type: 'text', text: 'hidden', when: 'Fa.Missing' },
+        { type: 'text', text: 'b' },
+      ],
+    };
+    const node = asRecord(interpretBlock(block, makeCtx(ROOT), coreRegistry, 0));
+    expect(node).toEqual({ stack: [{ text: 'a' }, { text: 'b' }] });
+  });
+
+  it('renders columns with a style', () => {
+    const block: Block = {
+      type: 'columns',
+      style: 'row',
+      columns: [
+        { type: 'text', text: 'left' },
+        { type: 'text', text: 'right' },
+      ],
+    };
+    const node = asRecord(interpretBlock(block, makeCtx(ROOT), coreRegistry, 0));
+    expect(node).toEqual({ columns: [{ text: 'left' }, { text: 'right' }], style: 'row' });
+  });
+
+  it('renders a divider canvas line', () => {
+    const node = asRecord(interpretBlock({ type: 'divider' }, makeCtx(ROOT), coreRegistry, 0));
+    expect(node).toEqual({
+      canvas: [{ type: 'line', x1: 0, y1: 0, x2: 515, y2: 0, lineWidth: 0.5, lineColor: '#cccccc' }],
+    });
+  });
+
+  it('attaches a style to a divider', () => {
+    const node = asRecord(
+      interpretBlock({ type: 'divider', style: 'rule' }, makeCtx(ROOT), coreRegistry, 0),
+    );
+    expect(node.style).toBe('rule');
+  });
+
+  it('renders a spacer with the default height', () => {
+    const node = asRecord(interpretBlock({ type: 'spacer' }, makeCtx(ROOT), coreRegistry, 0));
+    expect(node).toEqual({ text: '', margin: [0, 4, 0, 4] });
+  });
+
+  it('renders a spacer with a custom height', () => {
+    const node = asRecord(interpretBlock({ type: 'spacer', height: 20 }, makeCtx(ROOT), coreRegistry, 0));
+    expect(node).toEqual({ text: '', margin: [0, 10, 0, 10] });
+  });
+
+  it('returns null for a block whose `when` is false', () => {
+    const block: Block = { type: 'text', text: 'x', when: 'Fa.Missing' };
+    expect(interpretBlock(block, makeCtx(ROOT), coreRegistry, 0)).toBeNull();
+  });
+
+  it('renders a block whose `when` is true', () => {
+    const block: Block = { type: 'text', text: 'x', when: 'Fa.P_2' };
+    expect(interpretBlock(block, makeCtx(ROOT), coreRegistry, 0)).toEqual({ text: 'x' });
+  });
+});
+
+describe('interpretBlock errors + depth', () => {
+  it('throws KSeFPdfError for an unknown block type', () => {
+    const block = { type: 'nope' } as unknown as Block;
+    expect(() => interpretBlock(block, makeCtx(ROOT), coreRegistry, 0)).toThrow(KSeFPdfError);
+  });
+
+  it('throws KSeFPdfError when no renderer is registered (empty registry)', () => {
+    const block: Block = { type: 'text', text: 'x' };
+    expect(() => interpretBlock(block, makeCtx(ROOT), {}, 0)).toThrow(
+      /No renderer registered/,
+    );
+  });
+
+  it('throws KSeFPdfError when nesting exceeds MAX_DEPTH', () => {
+    let block: Block = { type: 'text', text: 'deep' };
+    for (let i = 0; i < MAX_DEPTH + 5; i++) {
+      block = { type: 'stack', stack: [block] };
+    }
+    expect(() => interpretBlock(block, makeCtx(ROOT), coreRegistry, 0)).toThrow(KSeFPdfError);
+    expect(() => interpretBlock(block, makeCtx(ROOT), coreRegistry, 0)).toThrow(
+      new RegExp(`maximum depth of ${MAX_DEPTH}`),
+    );
+  });
+});
+
+// ── interpretTemplate ───────────────────────────────────────────────────────
+
+/** Assemble an InvoiceTemplate literal (only the fields the interpreter reads). */
+function makeTemplate(partial: Partial<InvoiceTemplate> & { blocks: Block[] }): InvoiceTemplate {
+  return { schema: 'FA(3)', ...partial } as InvoiceTemplate;
+}
+
+describe('interpretTemplate', () => {
+  it('wires content and a Roboto default style', () => {
+    const template = makeTemplate({ blocks: [{ type: 'text', text: 'Hello' }] });
+    const doc = interpretTemplate(template, makeCtx(ROOT));
+    expect(doc.content).toEqual([{ text: 'Hello' }]);
+    expect(doc.defaultStyle).toEqual({ font: 'Roboto', fontSize: 9 });
+  });
+
+  it('merges a template defaultStyle over the Roboto default', () => {
+    const template = makeTemplate({
+      blocks: [{ type: 'text', text: 'x' }],
+      defaultStyle: { fontSize: 11, color: '#333' },
+    });
+    const doc = interpretTemplate(template, makeCtx(ROOT));
+    // Roboto font is kept; fontSize overridden; extra prop merged in.
+    expect(doc.defaultStyle).toEqual({ font: 'Roboto', fontSize: 11, color: '#333' });
+  });
+
+  it('wires named styles when present', () => {
+    const styles = { h1: { fontSize: 14, bold: true } };
+    const template = makeTemplate({ blocks: [{ type: 'text', text: 'x' }], styles });
+    const doc = interpretTemplate(template, makeCtx(ROOT));
+    expect(doc.styles).toEqual(styles);
+  });
+
+  it('omits styles when the template has none', () => {
+    const template = makeTemplate({ blocks: [{ type: 'text', text: 'x' }] });
+    const doc = interpretTemplate(template, makeCtx(ROOT));
+    expect('styles' in doc).toBe(false);
+  });
+
+  it('wires page size/orientation/margins when present', () => {
+    const template = makeTemplate({
+      blocks: [{ type: 'text', text: 'x' }],
+      page: { size: 'A4', orientation: 'landscape', margins: [10, 20, 30, 40] },
+    });
+    const doc = interpretTemplate(template, makeCtx(ROOT));
+    expect(doc.pageSize).toBe('A4');
+    expect(doc.pageOrientation).toBe('landscape');
+    expect(doc.pageMargins).toEqual([10, 20, 30, 40]);
+  });
+
+  it('omits page props when the page config is partial or absent', () => {
+    const template = makeTemplate({ blocks: [{ type: 'text', text: 'x' }], page: {} });
+    const doc = interpretTemplate(template, makeCtx(ROOT));
+    expect('pageSize' in doc).toBe(false);
+    expect('pageOrientation' in doc).toBe(false);
+    expect('pageMargins' in doc).toBe(false);
+  });
+
+  it('omits hidden blocks from content', () => {
+    const template = makeTemplate({
+      blocks: [
+        { type: 'text', text: 'visible' },
+        { type: 'text', text: 'gone', when: 'Fa.Missing' },
+      ],
+    });
+    const doc = interpretTemplate(template, makeCtx(ROOT));
+    expect(doc.content).toEqual([{ text: 'visible' }]);
+  });
+
+  it('flattens an array-returning custom renderer into content', () => {
+    const registry: BlockRegistry = {
+      qr: () => [{ text: 'a' }, { text: 'b' }],
+    };
+    const template = makeTemplate({
+      blocks: [{ type: 'text', text: 'first' }, { type: 'qr' }],
+    });
+    const doc = interpretTemplate(template, makeCtx(ROOT), registry);
+    expect(doc.content).toEqual([{ text: 'first' }, { text: 'a' }, { text: 'b' }]);
+  });
+
+  it('lets a custom registry override a core primitive', () => {
+    const registry: BlockRegistry = {
+      text: () => ({ text: 'OVERRIDDEN' }),
+    };
+    const template = makeTemplate({ blocks: [{ type: 'text', text: 'orig' }] });
+    const doc = interpretTemplate(template, makeCtx(ROOT), registry);
+    expect(doc.content).toEqual([{ text: 'OVERRIDDEN' }]);
+  });
+});
diff --git a/packages/ksef-client-ts/tests/unit/pdf/parse.test.ts b/packages/ksef-client-ts/tests/unit/pdf/parse.test.ts
new file mode 100644
index 0000000..7f11f81
--- /dev/null
+++ b/packages/ksef-client-ts/tests/unit/pdf/parse.test.ts
@@ -0,0 +1,154 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, it, expect } from 'vitest';
+import {
+  pdfXmlParser,
+  parseXmlForPdf,
+  detectInvoiceVersion,
+  detectUpoVersion,
+} from '../../../src/pdf/parse.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const fixturesDir = path.resolve(__dirname, '../../fixtures');
+
+function loadFixture(rel: string): string {
+  return fs.readFileSync(path.join(fixturesDir, rel), 'utf8');
+}
+
+const fa3Xml = loadFixture('pdf/fa3.xml');
+const fa2Xml = loadFixture('pdf/fa2.xml');
+const upoV43Xml = loadFixture('pdf/upo-4_3.xml');
+
+// Non-FA / non-Faktura roots for negative detection — inline so the test stays
+// self-contained and free of any personal invoice data.
+const pef3Xml =
+  '<Invoice xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2"><ID>1</ID></Invoice>';
+const rr1Xml =
+  '<FakturaRR><Naglowek><KodFormularza kodSystemowy="FA_RR (1)">FA_RR</KodFormularza></Naglowek></FakturaRR>';
+
+describe('pdfXmlParser', () => {
+  it('parses a mixed-content element into #text plus @-prefixed attributes', () => {
+    const parsed = pdfXmlParser.parse(
+      '<KodFormularza kodSystemowy="FA (3)" wersjaSchemy="1-0E">FA</KodFormularza>',
+    ) as Record<string, Record<string, unknown>>;
+    expect(parsed.KodFormularza).toEqual({
+      '#text': 'FA',
+      '@kodSystemowy': 'FA (3)',
+      '@wersjaSchemy': '1-0E',
+    });
+  });
+
+  it('strips namespace prefixes from element names', () => {
+    const parsed = pdfXmlParser.parse('<tns:Fa><tns:P_2>X</tns:P_2></tns:Fa>') as Record<
+      string,
+      Record<string, unknown>
+    >;
+    expect(parsed.Fa).toEqual({ P_2: 'X' });
+  });
+
+  it('keeps numeric-looking values as strings (parseTagValue: false)', () => {
+    const parsed = pdfXmlParser.parse('<P_8B>05</P_8B>') as Record<string, unknown>;
+    expect(parsed.P_8B).toBe('05');
+  });
+});
+
+describe('parseXmlForPdf', () => {
+  it('returns an object keyed by the document root', () => {
+    const parsed = parseXmlForPdf(fa3Xml);
+    expect(parsed).toHaveProperty('Faktura');
+  });
+
+  it('collapses a single repeated element into an object (not an array)', () => {
+    const parsed = parseXmlForPdf(fa3Xml) as {
+      Faktura: { Fa: { FaWiersz: unknown } };
+    };
+    expect(Array.isArray(parsed.Faktura.Fa.FaWiersz)).toBe(false);
+  });
+
+  it('returns {} for an empty string without throwing', () => {
+    expect(parseXmlForPdf('')).toEqual({});
+  });
+
+  it('returns {} for non-XML text without throwing', () => {
+    expect(parseXmlForPdf('just some text')).toEqual({});
+  });
+
+  it('does not throw on malformed / unterminated XML', () => {
+    expect(() => parseXmlForPdf('<a><b>oops')).not.toThrow();
+    expect(parseXmlForPdf('<a><b>oops')).toHaveProperty('a');
+  });
+});
+
+describe('detectInvoiceVersion', () => {
+  it('detects FA(3) from a real fixture', () => {
+    expect(detectInvoiceVersion(fa3Xml)).toBe('FA(3)');
+  });
+
+  it('detects FA(2) from a real fixture', () => {
+    expect(detectInvoiceVersion(fa2Xml)).toBe('FA(2)');
+  });
+
+  it('detects FA(3) via WariantFormularza when kodSystemowy is absent', () => {
+    const xml = '<Faktura><Naglowek><WariantFormularza>3</WariantFormularza></Naglowek></Faktura>';
+    expect(detectInvoiceVersion(xml)).toBe('FA(3)');
+  });
+
+  it('detects FA(2) via WariantFormularza when kodSystemowy is absent', () => {
+    const xml = '<Faktura><Naglowek><WariantFormularza>2</WariantFormularza></Naglowek></Faktura>';
+    expect(detectInvoiceVersion(xml)).toBe('FA(2)');
+  });
+
+  it('detects FA(3) from kodSystemowy alone (no WariantFormularza)', () => {
+    const xml =
+      '<Faktura><Naglowek><KodFormularza kodSystemowy="FA (3)">FA</KodFormularza></Naglowek></Faktura>';
+    expect(detectInvoiceVersion(xml)).toBe('FA(3)');
+  });
+
+  it('returns null for a Faktura with neither a recognized kod nor variant', () => {
+    const xml =
+      '<Faktura><Naglowek><WariantFormularza>1</WariantFormularza></Naglowek></Faktura>';
+    expect(detectInvoiceVersion(xml)).toBeNull();
+  });
+
+  it('returns null for a UPO document (no Faktura root)', () => {
+    expect(detectInvoiceVersion(upoV43Xml)).toBeNull();
+  });
+
+  it('returns null for a PEF/UBL Invoice (root is Invoice, not Faktura)', () => {
+    expect(detectInvoiceVersion(pef3Xml)).toBeNull();
+  });
+
+  it('returns null for a farmer invoice (root is FakturaRR, not Faktura)', () => {
+    expect(detectInvoiceVersion(rr1Xml)).toBeNull();
+  });
+
+  it('returns null for unrecognized / non-invoice XML', () => {
+    expect(detectInvoiceVersion('<Foo><Bar>baz</Bar></Foo>')).toBeNull();
+  });
+});
+
+describe('detectUpoVersion', () => {
+  it('detects UPO(4.3) from a real v4-3 fixture', () => {
+    expect(detectUpoVersion(upoV43Xml)).toBe('UPO(4.3)');
+  });
+
+  it('detects UPO(4.2) from a v4-2 namespace (raw-scan fallback)', () => {
+    const xml =
+      '<Potwierdzenie xmlns="http://upo.schematy.mf.gov.pl/KSeF/v4-2"><NumerReferencyjnySesji>X</NumerReferencyjnySesji></Potwierdzenie>';
+    expect(detectUpoVersion(xml)).toBe('UPO(4.2)');
+  });
+
+  it('returns null for a Potwierdzenie without a recognized version marker', () => {
+    const xml = '<Potwierdzenie xmlns="http://upo.schematy.mf.gov.pl/KSeF/v9-9"><X>1</X></Potwierdzenie>';
+    expect(detectUpoVersion(xml)).toBeNull();
+  });
+
+  it('returns null for a non-UPO document (no Potwierdzenie root)', () => {
+    expect(detectUpoVersion(fa3Xml)).toBeNull();
+  });
+
+  it('returns null for unrecognized XML', () => {
+    expect(detectUpoVersion('<Foo/>')).toBeNull();
+  });
+});
diff --git a/packages/ksef-client-ts/tests/unit/pdf/qr.test.ts b/packages/ksef-client-ts/tests/unit/pdf/qr.test.ts
new file mode 100644
index 0000000..de89564
--- /dev/null
+++ b/packages/ksef-client-ts/tests/unit/pdf/qr.test.ts
@@ -0,0 +1,146 @@
+import { describe, it, expect } from 'vitest';
+import crypto from 'node:crypto';
+import {
+  computeInvoiceHashBase64,
+  resolveBaseQrUrl,
+  deriveInvoiceQrUrl,
+} from '../../../src/pdf/qr.js';
+import { qrRenderer } from '../../../src/pdf/template/blocks/qr.js';
+import { VerificationLinkService } from '../../../src/qr/verification-link-service.js';
+import { Environment } from '../../../src/config/environments.js';
+import type { RenderContext } from '../../../src/pdf/template/interpret.js';
+import type { QrBlock } from '../../../src/pdf/template/dsl.js';
+
+/** Minimal parsed body: seller NIP + issue date, same shape as ctx.root. */
+const body = { Podmiot1: { DaneIdentyfikacyjne: { NIP: '5213003700' } }, P_1: '2025-01-15' };
+
+// A clean UTF-8 invoice payload with LF newlines and no BOM.
+const CLEAN = '<Faktura>\n<P_2>FV/1</P_2>\n</Faktura>';
+
+function base64ToBase64Url(b64: string): string {
+  return b64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+describe('computeInvoiceHashBase64 — byte-exact hash invariant', () => {
+  it('hashes a Uint8Array and the equivalent clean UTF-8 string to the SAME hash', () => {
+    const bytes = new TextEncoder().encode(CLEAN);
+    const fromBytes = computeInvoiceHashBase64(bytes);
+    const fromString = computeInvoiceHashBase64(CLEAN);
+
+    expect(fromBytes).toBe(fromString);
+    // Sanity: matches a raw node:crypto digest over the same bytes.
+    expect(fromString).toBe(crypto.createHash('sha256').update(Buffer.from(CLEAN, 'utf8')).digest('base64'));
+  });
+
+  it('returns standard base64 (not base64url)', () => {
+    const hash = computeInvoiceHashBase64(CLEAN);
+    // 32-byte digest → 44-char base64 with a trailing '=' pad.
+    expect(hash).toMatch(/^[A-Za-z0-9+/]+=*$/);
+    expect(hash).toHaveLength(44);
+  });
+
+  it('changes the hash when a BOM is prepended', () => {
+    const withBom = '' + CLEAN;
+    expect(computeInvoiceHashBase64(withBom)).not.toBe(computeInvoiceHashBase64(CLEAN));
+  });
+
+  it('changes the hash when newlines are CRLF instead of LF', () => {
+    const crlf = CLEAN.replace(/\n/g, '\r\n');
+    expect(computeInvoiceHashBase64(crlf)).not.toBe(computeInvoiceHashBase64(CLEAN));
+  });
+
+  it('changes the hash when the XML is pretty-printed', () => {
+    const pretty = '<Faktura>\n  <P_2>FV/1</P_2>\n</Faktura>';
+    expect(computeInvoiceHashBase64(pretty)).not.toBe(computeInvoiceHashBase64(CLEAN));
+  });
+});
+
+describe('resolveBaseQrUrl', () => {
+  it('override wins over env', () => {
+    expect(resolveBaseQrUrl('prod', 'https://custom.example')).toBe('https://custom.example');
+    expect(resolveBaseQrUrl(undefined, 'https://custom.example')).toBe('https://custom.example');
+  });
+
+  it('treats an empty-string override as no override (falls through to env)', () => {
+    expect(resolveBaseQrUrl('test', '')).toBe(Environment.TEST.qrUrl);
+  });
+
+  it('maps env → qrUrl', () => {
+    expect(resolveBaseQrUrl('prod')).toBe(Environment.PROD.qrUrl);
+    expect(resolveBaseQrUrl('test')).toBe(Environment.TEST.qrUrl);
+    expect(resolveBaseQrUrl('demo')).toBe(Environment.DEMO.qrUrl);
+  });
+
+  it('defaults to prod when env is undefined', () => {
+    expect(resolveBaseQrUrl(undefined)).toBe(Environment.PROD.qrUrl);
+  });
+});
+
+describe('deriveInvoiceQrUrl', () => {
+  it('equals VerificationLinkService.buildInvoiceVerificationUrl for the same inputs', () => {
+    const url = deriveInvoiceQrUrl({ rawInput: CLEAN, body, env: 'test' });
+
+    const base = Environment.TEST.qrUrl;
+    const hash = computeInvoiceHashBase64(CLEAN);
+    const expected = new VerificationLinkService(base).buildInvoiceVerificationUrl(
+      '5213003700',
+      '2025-01-15',
+      hash,
+    );
+
+    expect(url).toBe(expected);
+  });
+
+  it('honors an explicit baseQrUrl override', () => {
+    const url = deriveInvoiceQrUrl({ rawInput: CLEAN, body, baseQrUrl: 'https://custom.example' });
+    expect(url.startsWith('https://custom.example/invoice/5213003700/15-01-2025/')).toBe(true);
+  });
+
+  it('uses an invoiceHash override VERBATIM (does not recompute)', () => {
+    const override = 'AAAA++//zz==';
+    const withOverride = deriveInvoiceQrUrl({ rawInput: CLEAN, body, env: 'test', invoiceHash: override });
+    const withoutOverride = deriveInvoiceQrUrl({ rawInput: CLEAN, body, env: 'test' });
+
+    // URL carries the base64url form of the override, not the computed hash.
+    expect(withOverride.endsWith(base64ToBase64Url(override))).toBe(true);
+    expect(withOverride).not.toBe(withoutOverride);
+  });
+
+  it('passes strict through to the accessor (throws on a missing binding)', () => {
+    expect(() => deriveInvoiceQrUrl({ rawInput: CLEAN, body: {}, strict: true })).toThrow();
+  });
+});
+
+describe('qrRenderer', () => {
+  function ctxWith(bindings: Record<string, string>): RenderContext {
+    return {
+      root: body,
+      strict: false,
+      label: (k: string) => k,
+      bindings,
+      flags: {},
+    };
+  }
+  const noopRender = () => null;
+  const block: QrBlock = { type: 'qr' };
+
+  it('emits a qr node with default fit 100 when qrUrl is present', () => {
+    const out = qrRenderer(block, ctxWith({ qrUrl: 'https://qr/invoice/x' }), noopRender);
+    expect(out).toEqual({ qr: 'https://qr/invoice/x', fit: 100 });
+  });
+
+  it('honors a custom fit', () => {
+    const out = qrRenderer({ type: 'qr', fit: 64 }, ctxWith({ qrUrl: 'https://qr/invoice/x' }), noopRender);
+    expect(out).toEqual({ qr: 'https://qr/invoice/x', fit: 64 });
+  });
+
+  it('emits an empty text node when qrUrl binding is empty', () => {
+    const out = qrRenderer(block, ctxWith({ qrUrl: '' }), noopRender);
+    expect(out).toEqual({ text: '' });
+  });
+
+  it('emits an empty text node when qrUrl binding is absent', () => {
+    const out = qrRenderer(block, ctxWith({}), noopRender);
+    expect(out).toEqual({ text: '' });
+  });
+});
diff --git a/packages/ksef-client-ts/tests/unit/pdf/render-builtins.test.ts b/packages/ksef-client-ts/tests/unit/pdf/render-builtins.test.ts
new file mode 100644
index 0000000..93e8d71
--- /dev/null
+++ b/packages/ksef-client-ts/tests/unit/pdf/render-builtins.test.ts
@@ -0,0 +1,59 @@
+import { readFileSync } from 'node:fs';
+import { describe, it, expect } from 'vitest';
+import { renderInvoicePdf, renderUpoPdf } from '../../../src/pdf/index.js';
+
+const fx = (p: string) => readFileSync(new URL(`../../fixtures/${p}`, import.meta.url), 'utf8');
+const fa2 = fx('pdf/fa2.xml');
+const fa3 = fx('pdf/fa3.xml');
+const upo43 = fx('pdf/upo-4_3.xml');
+const upo42 = fx('pdf/upo-4_2.xml');
+
+const head = (b: Uint8Array) => Buffer.from(b.subarray(0, 5)).toString('latin1');
+const tail = (b: Uint8Array) => Buffer.from(b.subarray(-6)).toString('latin1').trim();
+const isPdf = (b: Uint8Array) => head(b) === '%PDF-' && tail(b).endsWith('%%EOF');
+
+describe('built-in templates render valid PDFs', () => {
+  it('fa2-default renders FA(2)', async () => {
+    expect(isPdf(await renderInvoicePdf(fa2, 'fa2-default'))).toBe(true);
+  });
+
+  it('fa3-default renders FA(3)', async () => {
+    expect(isPdf(await renderInvoicePdf(fa3, 'fa3-default'))).toBe(true);
+  });
+
+  it('upo-4_3 renders via renderUpoPdf (auto-detected version)', async () => {
+    expect(isPdf(await renderUpoPdf(upo43))).toBe(true);
+  });
+
+  it('upo-4_2 renders via renderUpoPdf (auto-detected version)', async () => {
+    expect(isPdf(await renderUpoPdf(upo42))).toBe(true);
+  });
+
+  it('rejects a non-UPO document in renderUpoPdf', async () => {
+    await expect(renderUpoPdf(fa3)).rejects.toThrow(/UPO/);
+  });
+});
+
+describe('built-in templates in strict mode against full fixtures', () => {
+  // valid-fa2 / valid-fa3 populate every path the default templates reference,
+  // so a dot-path typo in our own preset would surface as a thrown error here.
+  it('fa2-default is strict-clean', async () => {
+    expect(isPdf(await renderInvoicePdf(fa2, 'fa2-default', { strict: true }))).toBe(true);
+  });
+
+  it('fa3-default is strict-clean', async () => {
+    expect(isPdf(await renderInvoicePdf(fa3, 'fa3-default', { strict: true }))).toBe(true);
+  });
+});
+
+describe('QR embedding', () => {
+  it('renders fa3-default with qr enabled without error', async () => {
+    const bytes = await renderInvoicePdf(fa3, 'fa3-default', { qr: true, ksefNumber: '1234567890-20250115-ABCDEF-01' });
+    expect(isPdf(bytes)).toBe(true);
+  });
+
+  it('renders bilingual pl+en labels', async () => {
+    const bytes = await renderInvoicePdf(fa3, 'fa3-default', { locale: 'pl+en' });
+    expect(isPdf(bytes)).toBe(true);
+  });
+});
diff --git a/packages/ksef-client-ts/tests/unit/pdf/render-smoke.test.ts b/packages/ksef-client-ts/tests/unit/pdf/render-smoke.test.ts
new file mode 100644
index 0000000..1a8c27a
--- /dev/null
+++ b/packages/ksef-client-ts/tests/unit/pdf/render-smoke.test.ts
@@ -0,0 +1,69 @@
+import { readFileSync } from 'node:fs';
+import { describe, it, expect } from 'vitest';
+import {
+  renderInvoicePdf,
+  renderInvoicePdfFromTemplate,
+  detectInvoiceVersion,
+} from '../../../src/pdf/index.js';
+import { KSeFPdfError } from '../../../src/pdf/errors.js';
+import type { InvoiceTemplate } from '../../../src/pdf/template/dsl.js';
+
+const fa3 = readFileSync(new URL('../../fixtures/pdf/fa3.xml', import.meta.url), 'utf8');
+const fa2 = readFileSync(new URL('../../fixtures/pdf/fa2.xml', import.meta.url), 'utf8');
+
+function pdfEnvelope(bytes: Uint8Array): { head: string; tail: string } {
+  const head = Buffer.from(bytes.subarray(0, 5)).toString('latin1');
+  const tail = Buffer.from(bytes.subarray(-6)).toString('latin1').trim();
+  return { head, tail };
+}
+
+describe('renderInvoicePdf — end-to-end', () => {
+  it('renders an FA(3) invoice to a valid PDF envelope', async () => {
+    const bytes = await renderInvoicePdf(fa3, 'fa3-default');
+    expect(bytes).toBeInstanceOf(Uint8Array);
+    expect(bytes.length).toBeGreaterThan(1000);
+    const { head, tail } = pdfEnvelope(bytes);
+    expect(head).toBe('%PDF-');
+    expect(tail.endsWith('%%EOF')).toBe(true);
+  });
+
+  it('accepts a Uint8Array input', async () => {
+    const bytes = await renderInvoicePdf(new TextEncoder().encode(fa3), 'fa3-default');
+    expect(pdfEnvelope(bytes).head).toBe('%PDF-');
+  });
+
+  it('renders the built-in fa3-default in strict mode without a missing binding', async () => {
+    // valid-fa3.xml populates every path the built-in references.
+    const bytes = await renderInvoicePdf(fa3, 'fa3-default', { strict: true });
+    expect(pdfEnvelope(bytes).head).toBe('%PDF-');
+  });
+
+  it('throws a friendly error for an unknown built-in template', async () => {
+    await expect(renderInvoicePdf(fa3, 'does-not-exist')).rejects.toBeInstanceOf(KSeFPdfError);
+  });
+
+  it('rejects a template whose schema does not match the document version', async () => {
+    // fa3-default targets FA(3); feeding FA(2) must be rejected.
+    expect(detectInvoiceVersion(fa2)).toBe('FA(2)');
+    await expect(renderInvoicePdf(fa2, 'fa3-default')).rejects.toThrow(/FA\(3\).*FA\(2\)|FA\(2\).*FA\(3\)/);
+  });
+});
+
+describe('renderInvoicePdfFromTemplate — custom object', () => {
+  it('renders a minimal custom template', async () => {
+    const template: InvoiceTemplate = {
+      schema: 'FA(3)',
+      blocks: [
+        { type: 'header', title: { label: 'invoice' }, number: 'Fa.P_2', date: 'Fa.P_1' },
+        { type: 'text', path: 'Fa.P_15', format: 'money' },
+      ],
+    };
+    const bytes = await renderInvoicePdfFromTemplate(fa3, template);
+    expect(pdfEnvelope(bytes).head).toBe('%PDF-');
+  });
+
+  it('rejects a structurally invalid template', async () => {
+    const bad = { schema: 'FA(3)', blocks: [{ type: 'nope' }] } as unknown as InvoiceTemplate;
+    await expect(renderInvoicePdfFromTemplate(fa3, bad)).rejects.toThrow();
+  });
+});
diff --git a/packages/ksef-client-ts/tsconfig.pdf-check.json b/packages/ksef-client-ts/tsconfig.pdf-check.json
new file mode 100644
index 0000000..765c480
--- /dev/null
+++ b/packages/ksef-client-ts/tsconfig.pdf-check.json
@@ -0,0 +1,12 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "rootDir": ".",
+    "noEmit": true,
+    "module": "node16",
+    "moduleResolution": "node16",
+    "types": ["node"]
+  },
+  "include": ["tests/fixtures/pdf-types-check.ts"],
+  "exclude": []
+}
diff --git a/packages/ksef-client-ts/tsup.config.ts b/packages/ksef-client-ts/tsup.config.ts
index 03ec654..5fcd71d 100644
--- a/packages/ksef-client-ts/tsup.config.ts
+++ b/packages/ksef-client-ts/tsup.config.ts
@@ -2,7 +2,7 @@ import { defineConfig } from "tsup";
 
 export default defineConfig([
   {
-    entry: ["src/index.ts", "src/node.ts"],
+    entry: ["src/index.ts", "src/node.ts", "src/pdf/index.ts"],
     format: ["esm", "cjs"],
     dts: true,
     clean: true,
@@ -11,6 +11,8 @@ export default defineConfig([
     shims: true,
     target: "node18",
     removeNodeProtocol: false,
+    // pdfmake is an optional peer — never bundle it; it is loaded lazily at runtime.
+    external: ["pdfmake"],
   },
   {
     entry: { cli: "src/cli/index.ts" },
@@ -22,5 +24,8 @@ export default defineConfig([
     target: "node18",
     banner: { js: "#!/usr/bin/env node" },
     removeNodeProtocol: false,
+    // The CLI lazily bridges into ./pdf, which lazily imports pdfmake — keep it
+    // external so it is never pulled into the CLI bundle (optional peer).
+    external: ["pdfmake"],
   },
 ]);
diff --git a/yarn.lock b/yarn.lock
index 3a51c26..7ac28dd 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -260,6 +260,46 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@andrewbranch/untar.js@npm:^1.0.3":
+  version: 1.0.3
+  resolution: "@andrewbranch/untar.js@npm:1.0.3"
+  checksum: 10c0/16774208cd5bc2cace3c8c6ca608b2b9ab07719a44501e5553f72bffb63c5fbac0b715a4b1065a65d09e010d940ac3cd148ade44dd7d49682765fe09e2c3b2a8
+  languageName: node
+  linkType: hard
+
+"@arethetypeswrong/cli@npm:^0.18.4":
+  version: 0.18.4
+  resolution: "@arethetypeswrong/cli@npm:0.18.4"
+  dependencies:
+    "@arethetypeswrong/core": "npm:0.18.4"
+    chalk: "npm:^4.1.2"
+    cli-table3: "npm:^0.6.3"
+    commander: "npm:^10.0.1"
+    marked: "npm:^9.1.2"
+    marked-terminal: "npm:^7.1.0"
+    semver: "npm:^7.5.4"
+  bin:
+    attw: ./dist/index.js
+  checksum: 10c0/33fda6943521762f873fc3c508ac5544e4578de018abaed195b30d5db54b7e43a88e7725d70196da6cb67522a19cc1e636189784af53041dad8f68ee34476033
+  languageName: node
+  linkType: hard
+
+"@arethetypeswrong/core@npm:0.18.4":
+  version: 0.18.4
+  resolution: "@arethetypeswrong/core@npm:0.18.4"
+  dependencies:
+    "@andrewbranch/untar.js": "npm:^1.0.3"
+    "@loaderkit/resolve": "npm:^1.0.2"
+    cjs-module-lexer: "npm:^1.2.3"
+    fflate: "npm:^0.8.3"
+    lru-cache: "npm:^11.0.1"
+    semver: "npm:^7.5.4"
+    typescript: "npm:5.6.1-rc"
+    validate-npm-package-name: "npm:^5.0.0"
+  checksum: 10c0/988eb93c3eaa42216b19cda2cc2c3076bf36b7ba29bff7ce447931b2224eeb117cd37139ae6e3c18bbc5ebae22c9d7ca4a82af49420b64eec95c49585ba086dd
+  languageName: node
+  linkType: hard
+
 "@babel/helper-string-parser@npm:^7.29.7":
   version: 7.29.7
   resolution: "@babel/helper-string-parser@npm:7.29.7"
@@ -302,6 +342,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@braidai/lang@npm:^1.0.0":
+  version: 1.1.2
+  resolution: "@braidai/lang@npm:1.1.2"
+  checksum: 10c0/24bc85bf85dfe027102b19f418a591202b00cc8be12525ceff8adb65d5ebdda0dc1a0463c1e2cb6de1d85cd409012aa85850d9377bae61160162afbea278ab26
+  languageName: node
+  linkType: hard
+
 "@codemirror/autocomplete@npm:^6.0.0, @codemirror/autocomplete@npm:^6.18.3":
   version: 6.20.3
   resolution: "@codemirror/autocomplete@npm:6.20.3"
@@ -904,6 +951,52 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@foliojs-fork/fontkit@npm:^1.9.2":
+  version: 1.9.2
+  resolution: "@foliojs-fork/fontkit@npm:1.9.2"
+  dependencies:
+    "@foliojs-fork/restructure": "npm:^2.0.2"
+    brotli: "npm:^1.2.0"
+    clone: "npm:^1.0.4"
+    deep-equal: "npm:^1.0.0"
+    dfa: "npm:^1.2.0"
+    tiny-inflate: "npm:^1.0.2"
+    unicode-properties: "npm:^1.2.2"
+    unicode-trie: "npm:^2.0.0"
+  checksum: 10c0/0855b621942aeaec3a20261154532b3a4653cc530e5429954b9ec2bd61805a484a450a43229d0e836e78d08674ac729d81193ac03347b0e202646d900446ce84
+  languageName: node
+  linkType: hard
+
+"@foliojs-fork/linebreak@npm:^1.1.1, @foliojs-fork/linebreak@npm:^1.1.2":
+  version: 1.1.2
+  resolution: "@foliojs-fork/linebreak@npm:1.1.2"
+  dependencies:
+    base64-js: "npm:1.3.1"
+    unicode-trie: "npm:^2.0.0"
+  checksum: 10c0/5791eab874ae120bbe7bbd5a70675d3f88869376dfba3c76c61487b42275eeaf07026de22f074c5d4b5fdde900b43cac1289c6c142aca6015ccdb0da1166c3e8
+  languageName: node
+  linkType: hard
+
+"@foliojs-fork/pdfkit@npm:^0.15.3":
+  version: 0.15.3
+  resolution: "@foliojs-fork/pdfkit@npm:0.15.3"
+  dependencies:
+    "@foliojs-fork/fontkit": "npm:^1.9.2"
+    "@foliojs-fork/linebreak": "npm:^1.1.1"
+    crypto-js: "npm:^4.2.0"
+    jpeg-exif: "npm:^1.1.4"
+    png-js: "npm:^1.0.0"
+  checksum: 10c0/5f3edff0182a6e29d12891e1573be6837035de8d4a4aa446ebf5ee561224b6f11b059cda05dd82a91bbe3de2cedc9676c59980506d5daf209a5d564865a297cb
+  languageName: node
+  linkType: hard
+
+"@foliojs-fork/restructure@npm:^2.0.2":
+  version: 2.0.2
+  resolution: "@foliojs-fork/restructure@npm:2.0.2"
+  checksum: 10c0/f9e6e94f7377f467a93988ee85cf326f2db3edd3029530791aced6d530fd7862efb27b00212beb8df6f7458cbec4acb6b198b36535d1acee3fb413c1d5ac55ac
+  languageName: node
+  linkType: hard
+
 "@headlessui/tailwindcss@npm:^0.2.2":
   version: 0.2.2
   resolution: "@headlessui/tailwindcss@npm:0.2.2"
@@ -1113,6 +1206,15 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@loaderkit/resolve@npm:^1.0.2":
+  version: 1.0.6
+  resolution: "@loaderkit/resolve@npm:1.0.6"
+  dependencies:
+    "@braidai/lang": "npm:^1.0.0"
+  checksum: 10c0/e7dfcc0fa8f073c3048c9b8ef702d82dcc4390dc8d57438ac3a652e4936d66df2ca7ae8a4f2b6901157493dd42236156c1f47a5280f680a12bdef2f1b870135c
+  languageName: node
+  linkType: hard
+
 "@marijn/find-cluster-break@npm:^1.0.0":
   version: 1.0.2
   resolution: "@marijn/find-cluster-break@npm:1.0.2"
@@ -1351,6 +1453,15 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@publint/pack@npm:^0.1.4":
+  version: 0.1.5
+  resolution: "@publint/pack@npm:0.1.5"
+  dependencies:
+    tinyexec: "npm:^1.2.4"
+  checksum: 10c0/b92344164e5e0c9b7103a8451bf8b0dede475c04ce6150d8d0c2b5a37260068ad35e3869fdc283f6fbaf7e9f19644e2d3728c13e05a35e200f08dce6981fbd97
+  languageName: node
+  linkType: hard
+
 "@replit/codemirror-css-color-picker@npm:^6.3.0":
   version: 6.3.0
   resolution: "@replit/codemirror-css-color-picker@npm:6.3.0"
@@ -1960,6 +2071,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@sindresorhus/is@npm:^4.6.0":
+  version: 4.6.0
+  resolution: "@sindresorhus/is@npm:4.6.0"
+  checksum: 10c0/33b6fb1d0834ec8dd7689ddc0e2781c2bfd8b9c4e4bacbcb14111e0ae00621f2c264b8a7d36541799d74888b5dccdf422a891a5cb5a709ace26325eedc81e22e
+  languageName: node
+  linkType: hard
+
 "@sindresorhus/merge-streams@npm:^4.0.0":
   version: 4.0.0
   resolution: "@sindresorhus/merge-streams@npm:4.0.0"
@@ -2739,6 +2857,15 @@ __metadata:
   languageName: node
   linkType: hard
 
+"ansi-escapes@npm:^7.0.0":
+  version: 7.3.0
+  resolution: "ansi-escapes@npm:7.3.0"
+  dependencies:
+    environment: "npm:^1.0.0"
+  checksum: 10c0/068961d99f0ef28b661a4a9f84a5d645df93ccf3b9b93816cc7d46bbe1913321d4cdf156bb842a4e1e4583b7375c631fa963efb43001c4eb7ff9ab8f78fc0679
+  languageName: node
+  linkType: hard
+
 "ansi-regex@npm:^5.0.1":
   version: 5.0.1
   resolution: "ansi-regex@npm:5.0.1"
@@ -2746,14 +2873,14 @@ __metadata:
   languageName: node
   linkType: hard
 
-"ansi-regex@npm:^6.2.2":
+"ansi-regex@npm:^6.1.0, ansi-regex@npm:^6.2.2":
   version: 6.2.2
   resolution: "ansi-regex@npm:6.2.2"
   checksum: 10c0/05d4acb1d2f59ab2cf4b794339c7b168890d44dda4bf0ce01152a8da0213aca207802f930442ce8cd22d7a92f44907664aac6508904e75e038fa944d2601b30f
   languageName: node
   linkType: hard
 
-"ansi-styles@npm:^4.0.0":
+"ansi-styles@npm:^4.0.0, ansi-styles@npm:^4.1.0":
   version: 4.3.0
   resolution: "ansi-styles@npm:4.3.0"
   dependencies:
@@ -2828,6 +2955,20 @@ __metadata:
   languageName: node
   linkType: hard
 
+"async-function@npm:^1.0.0":
+  version: 1.0.0
+  resolution: "async-function@npm:1.0.0"
+  checksum: 10c0/669a32c2cb7e45091330c680e92eaeb791bc1d4132d827591e499cd1f776ff5a873e77e5f92d0ce795a8d60f10761dec9ddfe7225a5de680f5d357f67b1aac73
+  languageName: node
+  linkType: hard
+
+"async-generator-function@npm:^1.0.0":
+  version: 1.0.0
+  resolution: "async-generator-function@npm:1.0.0"
+  checksum: 10c0/2c50ef856c543ad500d8d8777d347e3c1ba623b93e99c9263ecc5f965c1b12d2a140e2ab6e43c3d0b85366110696f28114649411cbcd10b452a92a2318394186
+  languageName: node
+  linkType: hard
+
 "b4a@npm:^1.6.4, b4a@npm:^1.8.1":
   version: 1.8.1
   resolution: "b4a@npm:1.8.1"
@@ -2938,7 +3079,14 @@ __metadata:
   languageName: node
   linkType: hard
 
-"base64-js@npm:^1.3.1":
+"base64-js@npm:1.3.1":
+  version: 1.3.1
+  resolution: "base64-js@npm:1.3.1"
+  checksum: 10c0/f111a2c2b105eb9ee3818c30154e047fb00370699a03c2130d0944f10914697677ceb5faec64ea851e00710b80539afb03e9aa098e19c183a5e7a1cdc18abb29
+  languageName: node
+  linkType: hard
+
+"base64-js@npm:^1.1.2, base64-js@npm:^1.3.0, base64-js@npm:^1.3.1":
   version: 1.5.1
   resolution: "base64-js@npm:1.5.1"
   checksum: 10c0/f23823513b63173a001030fae4f2dabe283b99a9d324ade3ad3d148e218134676f1ee8568c877cd79ec1c53158dcf2d2ba527a97c606618928ba99dd930102bf
@@ -2999,6 +3147,24 @@ __metadata:
   languageName: node
   linkType: hard
 
+"brotli@npm:^1.2.0":
+  version: 1.3.3
+  resolution: "brotli@npm:1.3.3"
+  dependencies:
+    base64-js: "npm:^1.1.2"
+  checksum: 10c0/9d24e24f8b7eabf44af034ed5f7d5530008b835f09a107a84ac060723e86dd43c6aa68958691fe5df524f59473b35f5ce2e0854aa1152c0a254d1010f51bcf22
+  languageName: node
+  linkType: hard
+
+"browserify-zlib@npm:^0.2.0":
+  version: 0.2.0
+  resolution: "browserify-zlib@npm:0.2.0"
+  dependencies:
+    pako: "npm:~1.0.5"
+  checksum: 10c0/9ab10b6dc732c6c5ec8ebcbe5cb7fe1467f97402c9b2140113f47b5f187b9438f93a8e065d8baf8b929323c18324fbf1105af479ee86d9d36cab7d7ef3424ad9
+  languageName: node
+  linkType: hard
+
 "buffer-crc32@npm:^1.0.0":
   version: 1.0.0
   resolution: "buffer-crc32@npm:1.0.0"
@@ -3054,6 +3220,38 @@ __metadata:
   languageName: node
   linkType: hard
 
+"call-bind-apply-helpers@npm:^1.0.1, call-bind-apply-helpers@npm:^1.0.2":
+  version: 1.0.2
+  resolution: "call-bind-apply-helpers@npm:1.0.2"
+  dependencies:
+    es-errors: "npm:^1.3.0"
+    function-bind: "npm:^1.1.2"
+  checksum: 10c0/47bd9901d57b857590431243fea704ff18078b16890a6b3e021e12d279bbf211d039155e27d7566b374d49ee1f8189344bac9833dec7a20cdec370506361c938
+  languageName: node
+  linkType: hard
+
+"call-bind@npm:^1.0.7, call-bind@npm:^1.0.8":
+  version: 1.0.9
+  resolution: "call-bind@npm:1.0.9"
+  dependencies:
+    call-bind-apply-helpers: "npm:^1.0.2"
+    es-define-property: "npm:^1.0.1"
+    get-intrinsic: "npm:^1.3.0"
+    set-function-length: "npm:^1.2.2"
+  checksum: 10c0/a6621f6da1444481919ce3b4983dff725691e0754d3507ae483ce56e54985f2da7d6f1df512c56dbf28660745cf1ca52553f1fc9aef5557f3ce353ef14fab714
+  languageName: node
+  linkType: hard
+
+"call-bound@npm:^1.0.2":
+  version: 1.0.4
+  resolution: "call-bound@npm:1.0.4"
+  dependencies:
+    call-bind-apply-helpers: "npm:^1.0.2"
+    get-intrinsic: "npm:^1.3.0"
+  checksum: 10c0/f4796a6a0941e71c766aea672f63b72bc61234c4f4964dc6d7606e3664c307e7d77845328a8f3359ce39ddb377fed67318f9ee203dea1d47e46165dcf2917644
+  languageName: node
+  linkType: hard
+
 "camelcase@npm:^5.0.0":
   version: 5.3.1
   resolution: "camelcase@npm:5.3.1"
@@ -3081,13 +3279,30 @@ __metadata:
   languageName: node
   linkType: hard
 
-"chalk@npm:^5.6.2":
+"chalk@npm:^4.0.0, chalk@npm:^4.1.2":
+  version: 4.1.2
+  resolution: "chalk@npm:4.1.2"
+  dependencies:
+    ansi-styles: "npm:^4.1.0"
+    supports-color: "npm:^7.1.0"
+  checksum: 10c0/4a3fef5cc34975c898ffe77141450f679721df9dde00f6c304353fa9c8b571929123b26a0e4617bde5018977eb655b31970c297b91b63ee83bb82aeb04666880
+  languageName: node
+  linkType: hard
+
+"chalk@npm:^5.4.1, chalk@npm:^5.6.2":
   version: 5.6.2
   resolution: "chalk@npm:5.6.2"
   checksum: 10c0/99a4b0f0e7991796b1e7e3f52dceb9137cae2a9dfc8fc0784a550dc4c558e15ab32ed70b14b21b52beb2679b4892b41a0aa44249bcb996f01e125d58477c6976
   languageName: node
   linkType: hard
 
+"char-regex@npm:^1.0.2":
+  version: 1.0.2
+  resolution: "char-regex@npm:1.0.2"
+  checksum: 10c0/57a09a86371331e0be35d9083ba429e86c4f4648ecbe27455dbfb343037c16ee6fdc7f6b61f433a57cc5ded5561d71c56a150e018f40c2ffb7bc93a26dae341e
+  languageName: node
+  linkType: hard
+
 "character-entities-html4@npm:^2.0.0":
   version: 2.1.0
   resolution: "character-entities-html4@npm:2.1.0"
@@ -3153,7 +3368,30 @@ __metadata:
   languageName: node
   linkType: hard
 
-"cli-table3@npm:^0.6.5":
+"cjs-module-lexer@npm:^1.2.3":
+  version: 1.4.3
+  resolution: "cjs-module-lexer@npm:1.4.3"
+  checksum: 10c0/076b3af85adc4d65dbdab1b5b240fe5b45d44fcf0ef9d429044dd94d19be5589376805c44fb2d4b3e684e5fe6a9b7cf3e426476a6507c45283c5fc6ff95240be
+  languageName: node
+  linkType: hard
+
+"cli-highlight@npm:^2.1.11":
+  version: 2.1.11
+  resolution: "cli-highlight@npm:2.1.11"
+  dependencies:
+    chalk: "npm:^4.0.0"
+    highlight.js: "npm:^10.7.1"
+    mz: "npm:^2.4.0"
+    parse5: "npm:^5.1.1"
+    parse5-htmlparser2-tree-adapter: "npm:^6.0.0"
+    yargs: "npm:^16.0.0"
+  bin:
+    highlight: bin/highlight
+  checksum: 10c0/b5b4af3b968aa9df77eee449a400fbb659cf47c4b03a395370bd98d5554a00afaa5819b41a9a8a1ca0d37b0b896a94e57c65289b37359a25b700b1f56eb04852
+  languageName: node
+  linkType: hard
+
+"cli-table3@npm:^0.6.3, cli-table3@npm:^0.6.5":
   version: 0.6.5
   resolution: "cli-table3@npm:0.6.5"
   dependencies:
@@ -3177,6 +3415,24 @@ __metadata:
   languageName: node
   linkType: hard
 
+"cliui@npm:^7.0.2":
+  version: 7.0.4
+  resolution: "cliui@npm:7.0.4"
+  dependencies:
+    string-width: "npm:^4.2.0"
+    strip-ansi: "npm:^6.0.0"
+    wrap-ansi: "npm:^7.0.0"
+  checksum: 10c0/6035f5daf7383470cef82b3d3db00bec70afb3423538c50394386ffbbab135e26c3689c41791f911fa71b62d13d3863c712fdd70f0fbdffd938a1e6fd09aac00
+  languageName: node
+  linkType: hard
+
+"clone@npm:^1.0.4":
+  version: 1.0.4
+  resolution: "clone@npm:1.0.4"
+  checksum: 10c0/2176952b3649293473999a95d7bebfc9dc96410f6cbd3d2595cf12fd401f63a4bf41a7adbfd3ab2ff09ed60cb9870c58c6acdd18b87767366fabfc163700f13b
+  languageName: node
+  linkType: hard
+
 "clsx@npm:^2.1.1":
   version: 2.1.1
   resolution: "clsx@npm:2.1.1"
@@ -3207,6 +3463,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"commander@npm:^10.0.1":
+  version: 10.0.1
+  resolution: "commander@npm:10.0.1"
+  checksum: 10c0/53f33d8927758a911094adadda4b2cbac111a5b377d8706700587650fd8f45b0bbe336de4b5c3fe47fd61f420a3d9bd452b6e0e6e5600a7e74d7bf0174f6efe3
+  languageName: node
+  linkType: hard
+
 "commander@npm:^4.0.0":
   version: 4.1.1
   resolution: "commander@npm:4.1.1"
@@ -3276,6 +3539,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"crypto-js@npm:^4.2.0":
+  version: 4.2.0
+  resolution: "crypto-js@npm:4.2.0"
+  checksum: 10c0/8fbdf9d56f47aea0794ab87b0eb9833baf80b01a7c5c1b0edc7faf25f662fb69ab18dc2199e2afcac54670ff0cd9607a9045a3f7a80336cccd18d77a55b9fdf0
+  languageName: node
+  linkType: hard
+
 "csstype@npm:^3.2.3":
   version: 3.2.3
   resolution: "csstype@npm:3.2.3"
@@ -3341,6 +3611,20 @@ __metadata:
   languageName: node
   linkType: hard
 
+"deep-equal@npm:^1.0.0":
+  version: 1.1.2
+  resolution: "deep-equal@npm:1.1.2"
+  dependencies:
+    is-arguments: "npm:^1.1.1"
+    is-date-object: "npm:^1.0.5"
+    is-regex: "npm:^1.1.4"
+    object-is: "npm:^1.1.5"
+    object-keys: "npm:^1.1.1"
+    regexp.prototype.flags: "npm:^1.5.1"
+  checksum: 10c0/cd85d822d18e9b3e1532d0f6ba412d229aa9d22881d70da161674428ae96e47925191296f7cda29306bac252889007da40ed8449363bd1c96c708acb82068a00
+  languageName: node
+  linkType: hard
+
 "deep-extend@npm:^0.6.0":
   version: 0.6.0
   resolution: "deep-extend@npm:0.6.0"
@@ -3348,6 +3632,28 @@ __metadata:
   languageName: node
   linkType: hard
 
+"define-data-property@npm:^1.0.1, define-data-property@npm:^1.1.4":
+  version: 1.1.4
+  resolution: "define-data-property@npm:1.1.4"
+  dependencies:
+    es-define-property: "npm:^1.0.0"
+    es-errors: "npm:^1.3.0"
+    gopd: "npm:^1.0.1"
+  checksum: 10c0/dea0606d1483eb9db8d930d4eac62ca0fa16738b0b3e07046cddfacf7d8c868bbe13fa0cb263eb91c7d0d527960dc3f2f2471a69ed7816210307f6744fe62e37
+  languageName: node
+  linkType: hard
+
+"define-properties@npm:^1.2.1":
+  version: 1.2.1
+  resolution: "define-properties@npm:1.2.1"
+  dependencies:
+    define-data-property: "npm:^1.0.1"
+    has-property-descriptors: "npm:^1.0.0"
+    object-keys: "npm:^1.1.1"
+  checksum: 10c0/88a152319ffe1396ccc6ded510a3896e77efac7a1bfbaa174a7b00414a1747377e0bb525d303794a47cf30e805c2ec84e575758512c6e44a993076d29fd4e6c3
+  languageName: node
+  linkType: hard
+
 "defu@npm:^6.1.4":
   version: 6.1.7
   resolution: "defu@npm:6.1.7"
@@ -3378,6 +3684,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"dfa@npm:^1.2.0":
+  version: 1.2.0
+  resolution: "dfa@npm:1.2.0"
+  checksum: 10c0/ad12f0bc73b530876672e0a9dfbaa350eeff0c876580042734a004e462eca86d7749b9dedf6b067ba54f346137ab23d16615826bbfa424a3e01ab0e2786fad3c
+  languageName: node
+  linkType: hard
+
 "dijkstrajs@npm:^1.0.1":
   version: 1.0.3
   resolution: "dijkstrajs@npm:1.0.3"
@@ -3385,6 +3698,17 @@ __metadata:
   languageName: node
   linkType: hard
 
+"dunder-proto@npm:^1.0.1":
+  version: 1.0.1
+  resolution: "dunder-proto@npm:1.0.1"
+  dependencies:
+    call-bind-apply-helpers: "npm:^1.0.1"
+    es-errors: "npm:^1.3.0"
+    gopd: "npm:^1.2.0"
+  checksum: 10c0/199f2a0c1c16593ca0a145dbf76a962f8033ce3129f01284d48c45ed4e14fea9bbacd7b3610b6cdc33486cef20385ac054948fefc6272fcce645c09468f93031
+  languageName: node
+  linkType: hard
+
 "eastasianwidth@npm:^0.2.0":
   version: 0.2.0
   resolution: "eastasianwidth@npm:0.2.0"
@@ -3413,6 +3737,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"emojilib@npm:^2.4.0":
+  version: 2.4.0
+  resolution: "emojilib@npm:2.4.0"
+  checksum: 10c0/6e66ba8921175842193f974e18af448bb6adb0cf7aeea75e08b9d4ea8e9baba0e4a5347b46ed901491dcaba277485891c33a8d70b0560ca5cc9672a94c21ab8f
+  languageName: node
+  linkType: hard
+
 "encoding@npm:^0.1.13":
   version: 0.1.13
   resolution: "encoding@npm:0.1.13"
@@ -3459,6 +3790,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"environment@npm:^1.0.0":
+  version: 1.1.0
+  resolution: "environment@npm:1.1.0"
+  checksum: 10c0/fb26434b0b581ab397039e51ff3c92b34924a98b2039dcb47e41b7bca577b9dbf134a8eadb364415c74464b682e2d3afe1a4c0eb9873dc44ea814c5d3103331d
+  languageName: node
+  linkType: hard
+
 "err-code@npm:^2.0.2":
   version: 2.0.3
   resolution: "err-code@npm:2.0.3"
@@ -3466,6 +3804,20 @@ __metadata:
   languageName: node
   linkType: hard
 
+"es-define-property@npm:^1.0.0, es-define-property@npm:^1.0.1":
+  version: 1.0.1
+  resolution: "es-define-property@npm:1.0.1"
+  checksum: 10c0/3f54eb49c16c18707949ff25a1456728c883e81259f045003499efba399c08bad00deebf65cccde8c0e07908c1a225c9d472b7107e558f2a48e28d530e34527c
+  languageName: node
+  linkType: hard
+
+"es-errors@npm:^1.3.0":
+  version: 1.3.0
+  resolution: "es-errors@npm:1.3.0"
+  checksum: 10c0/0a61325670072f98d8ae3b914edab3559b6caa980f08054a3b872052640d91da01d38df55df797fcc916389d77fc92b8d5906cf028f4db46d7e3003abecbca85
+  languageName: node
+  linkType: hard
+
 "es-module-lexer@npm:^1.7.0":
   version: 1.7.0
   resolution: "es-module-lexer@npm:1.7.0"
@@ -3473,6 +3825,15 @@ __metadata:
   languageName: node
   linkType: hard
 
+"es-object-atoms@npm:^1.0.0, es-object-atoms@npm:^1.1.1":
+  version: 1.1.2
+  resolution: "es-object-atoms@npm:1.1.2"
+  dependencies:
+    es-errors: "npm:^1.3.0"
+  checksum: 10c0/1772861f094f739d6f41b579cfb9a18579daffeb434552a370a5fbef50a32d22227e27b63fdbb757b7ddd429d1b42fe52ccae7966d9302a2ec221b6f1b41bbc4
+  languageName: node
+  linkType: hard
+
 "esbuild@npm:^0.21.3":
   version: 0.21.5
   resolution: "esbuild@npm:0.21.5"
@@ -3642,6 +4003,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"escalade@npm:^3.1.1":
+  version: 3.2.0
+  resolution: "escalade@npm:3.2.0"
+  checksum: 10c0/ced4dd3a78e15897ed3be74e635110bbf3b08877b0a41be50dcb325ee0e0b5f65fc2d50e9845194d7c4633f327e2e1c6cce00a71b617c5673df0374201d67f65
+  languageName: node
+  linkType: hard
+
 "escape-string-regexp@npm:^5.0.0":
   version: 5.0.0
   resolution: "escape-string-regexp@npm:5.0.0"
@@ -3791,6 +4159,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"fflate@npm:^0.8.3":
+  version: 0.8.3
+  resolution: "fflate@npm:0.8.3"
+  checksum: 10c0/eab181ca37f5348ae76d4b6f840e0026e30220e33153289ac942222d8b9638237d486507dbcc09878d724095bd354993a2ee48bbee99c8f2c6440d4448719aa7
+  languageName: node
+  linkType: hard
+
 "file-uri-to-path@npm:1.0.0":
   version: 1.0.0
   resolution: "file-uri-to-path@npm:1.0.0"
@@ -3889,6 +4264,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"function-bind@npm:^1.1.2":
+  version: 1.1.2
+  resolution: "function-bind@npm:1.1.2"
+  checksum: 10c0/d8680ee1e5fcd4c197e4ac33b2b4dce03c71f4d91717292785703db200f5c21f977c568d28061226f9b5900cbcd2c84463646134fd5337e7925e0942bc3f46d5
+  languageName: node
+  linkType: hard
+
 "function-timeout@npm:^1.0.1":
   version: 1.0.2
   resolution: "function-timeout@npm:1.0.2"
@@ -3896,6 +4278,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"functions-have-names@npm:^1.2.3":
+  version: 1.2.3
+  resolution: "functions-have-names@npm:1.2.3"
+  checksum: 10c0/33e77fd29bddc2d9bb78ab3eb854c165909201f88c75faa8272e35899e2d35a8a642a15e7420ef945e1f64a9670d6aa3ec744106b2aa42be68ca5114025954ca
+  languageName: node
+  linkType: hard
+
 "fuse.js@npm:^7.1.0":
   version: 7.4.2
   resolution: "fuse.js@npm:7.4.2"
@@ -3903,7 +4292,14 @@ __metadata:
   languageName: node
   linkType: hard
 
-"get-caller-file@npm:^2.0.1":
+"generator-function@npm:^2.0.0":
+  version: 2.0.1
+  resolution: "generator-function@npm:2.0.1"
+  checksum: 10c0/8a9f59df0f01cfefafdb3b451b80555e5cf6d76487095db91ac461a0e682e4ff7a9dbce15f4ecec191e53586d59eece01949e05a4b4492879600bbbe8e28d6b8
+  languageName: node
+  linkType: hard
+
+"get-caller-file@npm:^2.0.1, get-caller-file@npm:^2.0.5":
   version: 2.0.5
   resolution: "get-caller-file@npm:2.0.5"
   checksum: 10c0/c6c7b60271931fa752aeb92f2b47e355eac1af3a2673f47c9589e8f8a41adc74d45551c1bc57b5e66a80609f10ffb72b6f575e4370d61cc3f7f3aaff01757cde
@@ -3917,6 +4313,27 @@ __metadata:
   languageName: node
   linkType: hard
 
+"get-intrinsic@npm:^1.2.4, get-intrinsic@npm:^1.3.0":
+  version: 1.3.1
+  resolution: "get-intrinsic@npm:1.3.1"
+  dependencies:
+    async-function: "npm:^1.0.0"
+    async-generator-function: "npm:^1.0.0"
+    call-bind-apply-helpers: "npm:^1.0.2"
+    es-define-property: "npm:^1.0.1"
+    es-errors: "npm:^1.3.0"
+    es-object-atoms: "npm:^1.1.1"
+    function-bind: "npm:^1.1.2"
+    generator-function: "npm:^2.0.0"
+    get-proto: "npm:^1.0.1"
+    gopd: "npm:^1.2.0"
+    has-symbols: "npm:^1.1.0"
+    hasown: "npm:^2.0.2"
+    math-intrinsics: "npm:^1.1.0"
+  checksum: 10c0/9f4ab0cf7efe0fd2c8185f52e6f637e708f3a112610c88869f8f041bb9ecc2ce44bf285dfdbdc6f4f7c277a5b88d8e94a432374d97cca22f3de7fc63795deb5d
+  languageName: node
+  linkType: hard
+
 "get-own-enumerable-keys@npm:^1.0.0":
   version: 1.0.0
   resolution: "get-own-enumerable-keys@npm:1.0.0"
@@ -3924,6 +4341,16 @@ __metadata:
   languageName: node
   linkType: hard
 
+"get-proto@npm:^1.0.1":
+  version: 1.0.1
+  resolution: "get-proto@npm:1.0.1"
+  dependencies:
+    dunder-proto: "npm:^1.0.1"
+    es-object-atoms: "npm:^1.0.0"
+  checksum: 10c0/9224acb44603c5526955e83510b9da41baf6ae73f7398875fba50edc5e944223a89c4a72b070fcd78beb5f7bdda58ecb6294adc28f7acfc0da05f76a2399643c
+  languageName: node
+  linkType: hard
+
 "github-from-package@npm:0.0.0":
   version: 0.0.0
   resolution: "github-from-package@npm:0.0.0"
@@ -3970,6 +4397,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"gopd@npm:^1.0.1, gopd@npm:^1.2.0":
+  version: 1.2.0
+  resolution: "gopd@npm:1.2.0"
+  checksum: 10c0/50fff1e04ba2b7737c097358534eacadad1e68d24cccee3272e04e007bed008e68d2614f3987788428fd192a5ae3889d08fb2331417e4fc4a9ab366b2043cead
+  languageName: node
+  linkType: hard
+
 "graceful-fs@npm:^4.2.6":
   version: 4.2.11
   resolution: "graceful-fs@npm:4.2.11"
@@ -3991,6 +4425,40 @@ __metadata:
   languageName: node
   linkType: hard
 
+"has-property-descriptors@npm:^1.0.0, has-property-descriptors@npm:^1.0.2":
+  version: 1.0.2
+  resolution: "has-property-descriptors@npm:1.0.2"
+  dependencies:
+    es-define-property: "npm:^1.0.0"
+  checksum: 10c0/253c1f59e80bb476cf0dde8ff5284505d90c3bdb762983c3514d36414290475fe3fd6f574929d84de2a8eec00d35cf07cb6776205ff32efd7c50719125f00236
+  languageName: node
+  linkType: hard
+
+"has-symbols@npm:^1.0.3, has-symbols@npm:^1.1.0":
+  version: 1.1.0
+  resolution: "has-symbols@npm:1.1.0"
+  checksum: 10c0/dde0a734b17ae51e84b10986e651c664379018d10b91b6b0e9b293eddb32f0f069688c841fb40f19e9611546130153e0a2a48fd7f512891fb000ddfa36f5a20e
+  languageName: node
+  linkType: hard
+
+"has-tostringtag@npm:^1.0.2":
+  version: 1.0.2
+  resolution: "has-tostringtag@npm:1.0.2"
+  dependencies:
+    has-symbols: "npm:^1.0.3"
+  checksum: 10c0/a8b166462192bafe3d9b6e420a1d581d93dd867adb61be223a17a8d6dad147aa77a8be32c961bb2f27b3ef893cae8d36f564ab651f5e9b7938ae86f74027c48c
+  languageName: node
+  linkType: hard
+
+"hasown@npm:^2.0.2":
+  version: 2.0.4
+  resolution: "hasown@npm:2.0.4"
+  dependencies:
+    function-bind: "npm:^1.1.2"
+  checksum: 10c0/2d8de939e270b70618f8cebb69746620db10617dbb495bc66ddad326955ea24d3ca4af133aff3eb7c1853e0218f867bc2b050ec26fe02e3aea58f880ffc5e506
+  languageName: node
+  linkType: hard
+
 "hast-util-embedded@npm:^3.0.0":
   version: 3.0.0
   resolution: "hast-util-embedded@npm:3.0.0"
@@ -4208,6 +4676,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"highlight.js@npm:^10.7.1":
+  version: 10.7.3
+  resolution: "highlight.js@npm:10.7.3"
+  checksum: 10c0/073837eaf816922427a9005c56c42ad8786473dc042332dfe7901aa065e92bc3d94ebf704975257526482066abb2c8677cc0326559bb8621e046c21c5991c434
+  languageName: node
+  linkType: hard
+
 "highlight.js@npm:^11.11.1, highlight.js@npm:~11.11.0":
   version: 11.11.1
   resolution: "highlight.js@npm:11.11.1"
@@ -4286,6 +4761,15 @@ __metadata:
   languageName: node
   linkType: hard
 
+"iconv-lite@npm:^0.7.1":
+  version: 0.7.3
+  resolution: "iconv-lite@npm:0.7.3"
+  dependencies:
+    safer-buffer: "npm:>= 2.1.2 < 3.0.0"
+  checksum: 10c0/be2fd2414f7e94be3a63063fa0ad5919c16bc7b6e00c77eea0765ced6db405739f38dd51016583058fba25cc1d0106ba30b83fbb7a7e32f824d4db76f23d8d33
+  languageName: node
+  linkType: hard
+
 "identifier-regex@npm:^1.0.0":
   version: 1.0.1
   resolution: "identifier-regex@npm:1.0.1"
@@ -4368,6 +4852,26 @@ __metadata:
   languageName: node
   linkType: hard
 
+"is-arguments@npm:^1.1.1":
+  version: 1.2.0
+  resolution: "is-arguments@npm:1.2.0"
+  dependencies:
+    call-bound: "npm:^1.0.2"
+    has-tostringtag: "npm:^1.0.2"
+  checksum: 10c0/6377344b31e9fcb707c6751ee89b11f132f32338e6a782ec2eac9393b0cbd32235dad93052998cda778ee058754860738341d8114910d50ada5615912bb929fc
+  languageName: node
+  linkType: hard
+
+"is-date-object@npm:^1.0.5":
+  version: 1.1.0
+  resolution: "is-date-object@npm:1.1.0"
+  dependencies:
+    call-bound: "npm:^1.0.2"
+    has-tostringtag: "npm:^1.0.2"
+  checksum: 10c0/1a4d199c8e9e9cac5128d32e6626fa7805175af9df015620ac0d5d45854ccf348ba494679d872d37301032e35a54fc7978fba1687e8721b2139aea7870cafa2f
+  languageName: node
+  linkType: hard
+
 "is-decimal@npm:^2.0.0":
   version: 2.0.1
   resolution: "is-decimal@npm:2.0.1"
@@ -4443,6 +4947,18 @@ __metadata:
   languageName: node
   linkType: hard
 
+"is-regex@npm:^1.1.4":
+  version: 1.2.1
+  resolution: "is-regex@npm:1.2.1"
+  dependencies:
+    call-bound: "npm:^1.0.2"
+    gopd: "npm:^1.2.0"
+    has-tostringtag: "npm:^1.0.2"
+    hasown: "npm:^2.0.2"
+  checksum: 10c0/1d3715d2b7889932349241680032e85d0b492cfcb045acb75ffc2c3085e8d561184f1f7e84b6f8321935b4aea39bc9c6ba74ed595b57ce4881a51dfdbc214e04
+  languageName: node
+  linkType: hard
+
 "is-regexp@npm:^3.1.0":
   version: 3.1.0
   resolution: "is-regexp@npm:3.1.0"
@@ -4544,6 +5060,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"jpeg-exif@npm:^1.1.4":
+  version: 1.1.4
+  resolution: "jpeg-exif@npm:1.1.4"
+  checksum: 10c0/0f9225b2423184d60c66b3d7361176801c17ede92fc9b3c044fcf00f379a5a1d424b360ecf0027dda47d405d253c7b62bf5b353fb08b2589e3650f38cc575e82
+  languageName: node
+  linkType: hard
+
 "js-base64@npm:^3.7.8":
   version: 3.7.8
   resolution: "js-base64@npm:3.7.8"
@@ -4624,6 +5147,7 @@ __metadata:
   version: 0.0.0-use.local
   resolution: "ksef-client-ts@workspace:packages/ksef-client-ts"
   dependencies:
+    "@arethetypeswrong/cli": "npm:^0.18.4"
     "@peculiar/x509": "npm:^1.12.3"
     "@scalar/api-reference": "npm:^1.49.3"
     "@types/node": "npm:^22.13.10"
@@ -4643,6 +5167,8 @@ __metadata:
     libxmljs2: "npm:^0.37.0"
     markdownlint-cli2: "npm:^0.22.1"
     node-forge: "npm:^1.3.1"
+    pdfmake: "npm:^0.2.20"
+    publint: "npm:^0.3.12"
     qrcode: "npm:^1.5.4"
     tar-stream: "npm:^3.2.0"
     tsup: "npm:^8.4.0"
@@ -4656,9 +5182,12 @@ __metadata:
     zod: "npm:^4.3.6"
   peerDependencies:
     libxmljs2: ^0.37.0
+    pdfmake: ^0.2.20
   peerDependenciesMeta:
     libxmljs2:
       optional: true
+    pdfmake:
+      optional: true
   bin:
     ksef: ./dist/cli.js
   languageName: unknown
@@ -4756,6 +5285,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"lru-cache@npm:^11.0.1":
+  version: 11.5.1
+  resolution: "lru-cache@npm:11.5.1"
+  checksum: 10c0/7b341cea79a8efe9c6a6f20c8757a77eca5b25d7ff983ccf4e11e547b81f6787824baa1c84705251dff84ab4ffac85717ac354b9d02e465f86a9f8b166409979
+  languageName: node
+  linkType: hard
+
 "magic-string@npm:^0.30.17, magic-string@npm:^0.30.21":
   version: 0.30.21
   resolution: "magic-string@npm:0.30.21"
@@ -4890,6 +5426,39 @@ __metadata:
   languageName: node
   linkType: hard
 
+"marked-terminal@npm:^7.1.0":
+  version: 7.3.0
+  resolution: "marked-terminal@npm:7.3.0"
+  dependencies:
+    ansi-escapes: "npm:^7.0.0"
+    ansi-regex: "npm:^6.1.0"
+    chalk: "npm:^5.4.1"
+    cli-highlight: "npm:^2.1.11"
+    cli-table3: "npm:^0.6.5"
+    node-emoji: "npm:^2.2.0"
+    supports-hyperlinks: "npm:^3.1.0"
+  peerDependencies:
+    marked: ">=1 <16"
+  checksum: 10c0/59d23c2ed9488c40856d828f431ae1d5d57426e791bbce8f05ec5a7d3a1f848cdb3b8d8880d76ae45570415f8b48ae459f50bbbd88ece5a31306f1e3de57f021
+  languageName: node
+  linkType: hard
+
+"marked@npm:^9.1.2":
+  version: 9.1.6
+  resolution: "marked@npm:9.1.6"
+  bin:
+    marked: bin/marked.js
+  checksum: 10c0/010bbd33c0f38300259c5d3bf0063deb36bab098d37ac0a3be5a35a65674a4c693427fc6704f486a89f638e9b36c36b8e220a93d47163f4e70e45a1fa8ca7b60
+  languageName: node
+  linkType: hard
+
+"math-intrinsics@npm:^1.1.0":
+  version: 1.1.0
+  resolution: "math-intrinsics@npm:1.1.0"
+  checksum: 10c0/7579ff94e899e2f76ab64491d76cf606274c874d8f2af4a442c016bd85688927fcfca157ba6bf74b08e9439dc010b248ce05b96cc7c126a354c3bae7fcb48b7f
+  languageName: node
+  linkType: hard
+
 "mdast-util-find-and-replace@npm:^3.0.0":
   version: 3.0.2
   resolution: "mdast-util-find-and-replace@npm:3.0.2"
@@ -5583,6 +6152,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"mri@npm:^1.1.0":
+  version: 1.2.0
+  resolution: "mri@npm:1.2.0"
+  checksum: 10c0/a3d32379c2554cf7351db6237ddc18dc9e54e4214953f3da105b97dc3babe0deb3ffe99cf409b38ea47cc29f9430561ba6b53b24ab8f9ce97a4b50409e4a50e7
+  languageName: node
+  linkType: hard
+
 "ms@npm:^2.1.3":
   version: 2.1.3
   resolution: "ms@npm:2.1.3"
@@ -5590,7 +6166,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"mz@npm:^2.7.0":
+"mz@npm:^2.4.0, mz@npm:^2.7.0":
   version: 2.7.0
   resolution: "mz@npm:2.7.0"
   dependencies:
@@ -5658,6 +6234,18 @@ __metadata:
   languageName: node
   linkType: hard
 
+"node-emoji@npm:^2.2.0":
+  version: 2.2.0
+  resolution: "node-emoji@npm:2.2.0"
+  dependencies:
+    "@sindresorhus/is": "npm:^4.6.0"
+    char-regex: "npm:^1.0.2"
+    emojilib: "npm:^2.4.0"
+    skin-tone: "npm:^2.0.0"
+  checksum: 10c0/9525defbd90a82a2131758c2470203fa2a2faa8edd177147a8654a26307fe03594e52847ecbe2746d06cfc5c50acd12bd500f035350a7609e8217c9894c19aad
+  languageName: node
+  linkType: hard
+
 "node-forge@npm:^1.3.1":
   version: 1.4.0
   resolution: "node-forge@npm:1.4.0"
@@ -5734,6 +6322,23 @@ __metadata:
   languageName: node
   linkType: hard
 
+"object-is@npm:^1.1.5":
+  version: 1.1.6
+  resolution: "object-is@npm:1.1.6"
+  dependencies:
+    call-bind: "npm:^1.0.7"
+    define-properties: "npm:^1.2.1"
+  checksum: 10c0/506af444c4dce7f8e31f34fc549e2fb8152d6b9c4a30c6e62852badd7f520b579c679af433e7a072f9d78eb7808d230dc12e1cf58da9154dfbf8813099ea0fe0
+  languageName: node
+  linkType: hard
+
+"object-keys@npm:^1.1.1":
+  version: 1.1.1
+  resolution: "object-keys@npm:1.1.1"
+  checksum: 10c0/b11f7ccdbc6d406d1f186cdadb9d54738e347b2692a14439ca5ac70c225fa6db46db809711b78589866d47b25fc3e8dee0b4c722ac751e11180f9380e3d8601d
+  languageName: node
+  linkType: hard
+
 "once@npm:^1.3.1, once@npm:^1.4.0":
   version: 1.4.0
   resolution: "once@npm:1.4.0"
@@ -5809,7 +6414,21 @@ __metadata:
   languageName: node
   linkType: hard
 
-"pako@npm:~1.0.2":
+"package-manager-detector@npm:^1.6.0":
+  version: 1.7.0
+  resolution: "package-manager-detector@npm:1.7.0"
+  checksum: 10c0/49488e732ef854205b8c58f68f2315c5b1006169bf9b3a34ca3042c2995edf53e805ee720778f214f32bb80cf6e7cc1ac13508423e89decc691c28329ade6a7d
+  languageName: node
+  linkType: hard
+
+"pako@npm:^0.2.5":
+  version: 0.2.9
+  resolution: "pako@npm:0.2.9"
+  checksum: 10c0/79c1806ebcf325b60ae599e4d7227c2e346d7b829dc20f5cf24cef07c934079dc3a61c5b3c8278a2f7a190c4a613e343ea11e5302dbe252efd11712df4b6b041
+  languageName: node
+  linkType: hard
+
+"pako@npm:~1.0.2, pako@npm:~1.0.5":
   version: 1.0.11
   resolution: "pako@npm:1.0.11"
   checksum: 10c0/86dd99d8b34c3930345b8bbeb5e1cd8a05f608eeb40967b293f72fe469d0e9c88b783a8777e4cc7dc7c91ce54c5e93d88ff4b4f060e6ff18408fd21030d9ffbe
@@ -5838,6 +6457,29 @@ __metadata:
   languageName: node
   linkType: hard
 
+"parse5-htmlparser2-tree-adapter@npm:^6.0.0":
+  version: 6.0.1
+  resolution: "parse5-htmlparser2-tree-adapter@npm:6.0.1"
+  dependencies:
+    parse5: "npm:^6.0.1"
+  checksum: 10c0/dfa5960e2aaf125707e19a4b1bc333de49232eba5a6ffffb95d313a7d6087c3b7a274b58bee8d3bd41bdf150638815d1d601a42bbf2a0345208c3c35b1279556
+  languageName: node
+  linkType: hard
+
+"parse5@npm:^5.1.1":
+  version: 5.1.1
+  resolution: "parse5@npm:5.1.1"
+  checksum: 10c0/b0f87a77a7fea5f242e3d76917c983bbea47703b9371801d51536b78942db6441cbda174bf84eb30e47315ddc6f8a0b57d68e562c790154430270acd76c1fa03
+  languageName: node
+  linkType: hard
+
+"parse5@npm:^6.0.1":
+  version: 6.0.1
+  resolution: "parse5@npm:6.0.1"
+  checksum: 10c0/595821edc094ecbcfb9ddcb46a3e1fe3a718540f8320eff08b8cf6742a5114cce2d46d45f95c26191c11b184dcaf4e2960abcd9c5ed9eb9393ac9a37efcfdecb
+  languageName: node
+  linkType: hard
+
 "parse5@npm:^7.0.0":
   version: 7.3.0
   resolution: "parse5@npm:7.3.0"
@@ -5892,6 +6534,18 @@ __metadata:
   languageName: node
   linkType: hard
 
+"pdfmake@npm:^0.2.20":
+  version: 0.2.23
+  resolution: "pdfmake@npm:0.2.23"
+  dependencies:
+    "@foliojs-fork/linebreak": "npm:^1.1.2"
+    "@foliojs-fork/pdfkit": "npm:^0.15.3"
+    iconv-lite: "npm:^0.7.1"
+    xmldoc: "npm:^2.0.3"
+  checksum: 10c0/c94ea1d3efbcbbb4f683f50501f2f864e69682f3b90e5d0680fb8e631efb29f540dedae25a71565aecee5b1402c5d0024b0a4333cf218190c11a2ec6b4529a87
+  languageName: node
+  linkType: hard
+
 "pend@npm:~1.2.0":
   version: 1.2.0
   resolution: "pend@npm:1.2.0"
@@ -5945,6 +6599,15 @@ __metadata:
   languageName: node
   linkType: hard
 
+"png-js@npm:^1.0.0":
+  version: 1.1.0
+  resolution: "png-js@npm:1.1.0"
+  dependencies:
+    browserify-zlib: "npm:^0.2.0"
+  checksum: 10c0/61e275cb424b914fbc01c2a1b0096857f214c5fee45054c713dec1ad320760f4dd61f28bb0b3b0c139bd8c49def8891b02ca4018238e7b5f14bb671cd1ca7874
+  languageName: node
+  linkType: hard
+
 "pngjs@npm:^5.0.0":
   version: 5.0.0
   resolution: "pngjs@npm:5.0.0"
@@ -6062,6 +6725,20 @@ __metadata:
   languageName: node
   linkType: hard
 
+"publint@npm:^0.3.12":
+  version: 0.3.21
+  resolution: "publint@npm:0.3.21"
+  dependencies:
+    "@publint/pack": "npm:^0.1.4"
+    package-manager-detector: "npm:^1.6.0"
+    picocolors: "npm:^1.1.1"
+    sade: "npm:^1.8.1"
+  bin:
+    publint: src/cli.js
+  checksum: 10c0/46f54061b112f852523e8b1357c5b454633008056de86f6acbbabcb155a8ab758d3e575df9f82fa37b7ba4a25bde8e68f98866763929eaef8c6d96ff1f761cea
+  languageName: node
+  linkType: hard
+
 "pump@npm:^3.0.0":
   version: 3.0.4
   resolution: "pump@npm:3.0.4"
@@ -6222,6 +6899,20 @@ __metadata:
   languageName: node
   linkType: hard
 
+"regexp.prototype.flags@npm:^1.5.1":
+  version: 1.5.4
+  resolution: "regexp.prototype.flags@npm:1.5.4"
+  dependencies:
+    call-bind: "npm:^1.0.8"
+    define-properties: "npm:^1.2.1"
+    es-errors: "npm:^1.3.0"
+    get-proto: "npm:^1.0.1"
+    gopd: "npm:^1.2.0"
+    set-function-name: "npm:^2.0.2"
+  checksum: 10c0/83b88e6115b4af1c537f8dabf5c3744032cb875d63bc05c288b1b8c0ef37cbe55353f95d8ca817e8843806e3e150b118bc624e4279b24b4776b4198232735a77
+  languageName: node
+  linkType: hard
+
 "rehype-external-links@npm:^3.0.0":
   version: 3.0.0
   resolution: "rehype-external-links@npm:3.0.0"
@@ -6493,6 +7184,15 @@ __metadata:
   languageName: node
   linkType: hard
 
+"sade@npm:^1.8.1":
+  version: 1.8.1
+  resolution: "sade@npm:1.8.1"
+  dependencies:
+    mri: "npm:^1.1.0"
+  checksum: 10c0/da8a3a5d667ad5ce3bf6d4f054bbb9f711103e5df21003c5a5c1a8a77ce12b640ed4017dd423b13c2307ea7e645adee7c2ae3afe8051b9db16a6f6d3da3f90b1
+  languageName: node
+  linkType: hard
+
 "safe-buffer@npm:^5.0.1, safe-buffer@npm:~5.2.0":
   version: 5.2.1
   resolution: "safe-buffer@npm:5.2.1"
@@ -6514,6 +7214,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"sax@npm:^1.4.3":
+  version: 1.6.0
+  resolution: "sax@npm:1.6.0"
+  checksum: 10c0/e5593f4a91eb25761a688c4d96902e4e95a0dd6017bc65146b6f21236e3d715cf893333b76bc758923c9574c2fb5a7a76c3a81e96ea15432f2624f906c027c1e
+  languageName: node
+  linkType: hard
+
 "semver@npm:^7.3.5, semver@npm:^7.5.3":
   version: 7.8.4
   resolution: "semver@npm:7.8.4"
@@ -6523,6 +7230,15 @@ __metadata:
   languageName: node
   linkType: hard
 
+"semver@npm:^7.5.4":
+  version: 7.8.5
+  resolution: "semver@npm:7.8.5"
+  bin:
+    semver: bin/semver.js
+  checksum: 10c0/b1f3127a5be8125a94f37188b361c212466c292c6910adce3ec106cff5dc211ccaedc4739c11bb70fda59d6fc1f040a9bca289f4e093451521a2372e5231fe0c
+  languageName: node
+  linkType: hard
+
 "set-blocking@npm:^2.0.0":
   version: 2.0.0
   resolution: "set-blocking@npm:2.0.0"
@@ -6537,6 +7253,32 @@ __metadata:
   languageName: node
   linkType: hard
 
+"set-function-length@npm:^1.2.2":
+  version: 1.2.2
+  resolution: "set-function-length@npm:1.2.2"
+  dependencies:
+    define-data-property: "npm:^1.1.4"
+    es-errors: "npm:^1.3.0"
+    function-bind: "npm:^1.1.2"
+    get-intrinsic: "npm:^1.2.4"
+    gopd: "npm:^1.0.1"
+    has-property-descriptors: "npm:^1.0.2"
+  checksum: 10c0/82850e62f412a258b71e123d4ed3873fa9377c216809551192bb6769329340176f109c2eeae8c22a8d386c76739855f78e8716515c818bcaef384b51110f0f3c
+  languageName: node
+  linkType: hard
+
+"set-function-name@npm:^2.0.2":
+  version: 2.0.2
+  resolution: "set-function-name@npm:2.0.2"
+  dependencies:
+    define-data-property: "npm:^1.1.4"
+    es-errors: "npm:^1.3.0"
+    functions-have-names: "npm:^1.2.3"
+    has-property-descriptors: "npm:^1.0.2"
+  checksum: 10c0/fce59f90696c450a8523e754abb305e2b8c73586452619c2bad5f7bf38c7b6b4651895c9db895679c5bef9554339cf3ef1c329b66ece3eda7255785fbe299316
+  languageName: node
+  linkType: hard
+
 "setimmediate@npm:^1.0.5":
   version: 1.0.5
   resolution: "setimmediate@npm:1.0.5"
@@ -6608,6 +7350,15 @@ __metadata:
   languageName: node
   linkType: hard
 
+"skin-tone@npm:^2.0.0":
+  version: 2.0.0
+  resolution: "skin-tone@npm:2.0.0"
+  dependencies:
+    unicode-emoji-modifier-base: "npm:^1.0.0"
+  checksum: 10c0/82d4c2527864f9cbd6cb7f3c4abb31e2224752234d5013b881d3e34e9ab543545b05206df5a17d14b515459fcb265ce409f9cfe443903176b0360cd20e4e4ba5
+  languageName: node
+  linkType: hard
+
 "slash@npm:^5.1.0":
   version: 5.1.0
   resolution: "slash@npm:5.1.0"
@@ -6886,7 +7637,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"supports-color@npm:^7.1.0":
+"supports-color@npm:^7.0.0, supports-color@npm:^7.1.0":
   version: 7.2.0
   resolution: "supports-color@npm:7.2.0"
   dependencies:
@@ -6895,6 +7646,16 @@ __metadata:
   languageName: node
   linkType: hard
 
+"supports-hyperlinks@npm:^3.1.0":
+  version: 3.2.0
+  resolution: "supports-hyperlinks@npm:3.2.0"
+  dependencies:
+    has-flag: "npm:^4.0.0"
+    supports-color: "npm:^7.0.0"
+  checksum: 10c0/bca527f38d4c45bc95d6a24225944675746c515ddb91e2456d00ae0b5c537658e9dd8155b996b191941b0c19036195a098251304b9082bbe00cd1781f3cd838e
+  languageName: node
+  linkType: hard
+
 "swrv@npm:^1.0.4":
   version: 1.2.0
   resolution: "swrv@npm:1.2.0"
@@ -7031,6 +7792,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"tiny-inflate@npm:^1.0.0, tiny-inflate@npm:^1.0.2":
+  version: 1.0.3
+  resolution: "tiny-inflate@npm:1.0.3"
+  checksum: 10c0/fab687537254f6ec44c9a2e880048fe70da3542aba28f73cda3e74c95cabf342a339372f2a6c032e322324f01accc03ca26c04ba2bad9b3eb8cf3ee99bba7f9b
+  languageName: node
+  linkType: hard
+
 "tinybench@npm:^2.9.0":
   version: 2.9.0
   resolution: "tinybench@npm:2.9.0"
@@ -7045,6 +7813,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"tinyexec@npm:^1.2.4":
+  version: 1.2.4
+  resolution: "tinyexec@npm:1.2.4"
+  checksum: 10c0/153b8db6b080194b558ff145b9cffc36b80a6e07babd644dcfbe49c807eee668c876049d28bdee90b96304476f883352f2dad91b3f86bc23832532f4363e66ff
+  languageName: node
+  linkType: hard
+
 "tinyglobby@npm:^0.2.11, tinyglobby@npm:^0.2.12, tinyglobby@npm:^0.2.14, tinyglobby@npm:^0.2.15":
   version: 0.2.17
   resolution: "tinyglobby@npm:0.2.17"
@@ -7216,6 +7991,16 @@ __metadata:
   languageName: node
   linkType: hard
 
+"typescript@npm:5.6.1-rc":
+  version: 5.6.1-rc
+  resolution: "typescript@npm:5.6.1-rc"
+  bin:
+    tsc: bin/tsc
+    tsserver: bin/tsserver
+  checksum: 10c0/9d6e99b7ddbc797ebc8d09e5d7f2f81ce5f288a4e607bcded3c545ced8582796c937fba31bede5660a56f978b2f68e7c4ee85614b307425a2b4617535721509f
+  languageName: node
+  linkType: hard
+
 "typescript@npm:^5.8.2":
   version: 5.9.3
   resolution: "typescript@npm:5.9.3"
@@ -7226,6 +8011,16 @@ __metadata:
   languageName: node
   linkType: hard
 
+"typescript@patch:typescript@npm%3A5.6.1-rc#optional!builtin<compat/typescript>":
+  version: 5.6.1-rc
+  resolution: "typescript@patch:typescript@npm%3A5.6.1-rc#optional!builtin<compat/typescript>::version=5.6.1-rc&hash=8c6c40"
+  bin:
+    tsc: bin/tsc
+    tsserver: bin/tsserver
+  checksum: 10c0/9c6f8d864bc2efc964d1bfc94bf2e14f35cd2ad3df5e92d5304c8759674ba77ae927078a5fc06a527c087953615465dd5decc2d4d28ca8e13c11f9b29e068d93
+  languageName: node
+  linkType: hard
+
 "typescript@patch:typescript@npm%3A^5.8.2#optional!builtin<compat/typescript>":
   version: 5.9.3
   resolution: "typescript@patch:typescript@npm%3A5.9.3#optional!builtin<compat/typescript>::version=5.9.3&hash=5786d5"
@@ -7287,6 +8082,33 @@ __metadata:
   languageName: node
   linkType: hard
 
+"unicode-emoji-modifier-base@npm:^1.0.0":
+  version: 1.0.0
+  resolution: "unicode-emoji-modifier-base@npm:1.0.0"
+  checksum: 10c0/b37623fcf0162186debd20f116483e035a2d5b905b932a2c472459d9143d446ebcbefb2a494e2fe4fa7434355396e2a95ec3fc1f0c29a3bc8f2c827220e79c66
+  languageName: node
+  linkType: hard
+
+"unicode-properties@npm:^1.2.2":
+  version: 1.4.1
+  resolution: "unicode-properties@npm:1.4.1"
+  dependencies:
+    base64-js: "npm:^1.3.0"
+    unicode-trie: "npm:^2.0.0"
+  checksum: 10c0/1d140b7945664fb0ef53de955170821e077b949eef377c6e4905902f07e339039271bfa2a005e4f4c6074b080d3420b486c52dc905e11f924949a04d1fb47ffd
+  languageName: node
+  linkType: hard
+
+"unicode-trie@npm:^2.0.0":
+  version: 2.0.0
+  resolution: "unicode-trie@npm:2.0.0"
+  dependencies:
+    pako: "npm:^0.2.5"
+    tiny-inflate: "npm:^1.0.0"
+  checksum: 10c0/2422368645249f315640a1c9e9506046aa7738fc9c5d59e15c207cdd6ec66101c35b0b9f75dc3ac28fe7be19aaf1efc898bbea074fa1e8e295ef736aeb7904bb
+  languageName: node
+  linkType: hard
+
 "unicorn-magic@npm:^0.4.0":
   version: 0.4.0
   resolution: "unicorn-magic@npm:0.4.0"
@@ -7392,6 +8214,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"validate-npm-package-name@npm:^5.0.0":
+  version: 5.0.1
+  resolution: "validate-npm-package-name@npm:5.0.1"
+  checksum: 10c0/903e738f7387404bb72f7ac34e45d7010c877abd2803dc2d614612527927a40a6d024420033132e667b1bade94544b8a1f65c9431a4eb30d0ce0d80093cd1f74
+  languageName: node
+  linkType: hard
+
 "vfile-location@npm:^5.0.0":
   version: 5.0.3
   resolution: "vfile-location@npm:5.0.3"
@@ -7748,7 +8577,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"wrap-ansi-cjs@npm:wrap-ansi@^7.0.0":
+"wrap-ansi-cjs@npm:wrap-ansi@^7.0.0, wrap-ansi@npm:^7.0.0":
   version: 7.0.0
   resolution: "wrap-ansi@npm:7.0.0"
   dependencies:
@@ -7806,6 +8635,15 @@ __metadata:
   languageName: node
   linkType: hard
 
+"xmldoc@npm:^2.0.3":
+  version: 2.0.3
+  resolution: "xmldoc@npm:2.0.3"
+  dependencies:
+    sax: "npm:^1.4.3"
+  checksum: 10c0/8b01fc2b49f7dfa3fc0506d7ae4bab41476e15836114a1ab3794a5dc925498e2f4c248391479f57426e166a718082e6628c7112a89e6bf015ed780c9772f4406
+  languageName: node
+  linkType: hard
+
 "xpath@npm:^0.0.33":
   version: 0.0.33
   resolution: "xpath@npm:0.0.33"
@@ -7820,6 +8658,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"y18n@npm:^5.0.5":
+  version: 5.0.8
+  resolution: "y18n@npm:5.0.8"
+  checksum: 10c0/4df2842c36e468590c3691c894bc9cdbac41f520566e76e24f59401ba7d8b4811eb1e34524d57e54bc6d864bcb66baab7ffd9ca42bf1eda596618f9162b91249
+  languageName: node
+  linkType: hard
+
 "yallist@npm:^4.0.0":
   version: 4.0.0
   resolution: "yallist@npm:4.0.0"
@@ -7853,6 +8698,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"yargs-parser@npm:^20.2.2":
+  version: 20.2.9
+  resolution: "yargs-parser@npm:20.2.9"
+  checksum: 10c0/0685a8e58bbfb57fab6aefe03c6da904a59769bd803a722bb098bd5b0f29d274a1357762c7258fb487512811b8063fb5d2824a3415a0a4540598335b3b086c72
+  languageName: node
+  linkType: hard
+
 "yargs@npm:^15.3.1":
   version: 15.4.1
   resolution: "yargs@npm:15.4.1"
@@ -7872,6 +8724,21 @@ __metadata:
   languageName: node
   linkType: hard
 
+"yargs@npm:^16.0.0":
+  version: 16.2.2
+  resolution: "yargs@npm:16.2.2"
+  dependencies:
+    cliui: "npm:^7.0.2"
+    escalade: "npm:^3.1.1"
+    get-caller-file: "npm:^2.0.5"
+    require-directory: "npm:^2.1.1"
+    string-width: "npm:^4.2.0"
+    y18n: "npm:^5.0.5"
+    yargs-parser: "npm:^20.2.2"
+  checksum: 10c0/1ca2152581ee7c9c9fb4174767ff7294b1c272d2d0a1f6eb13c39ce177fded85eb9c96711e00cd7913c0a9b88b6e763713ee11cae81b9b62fd97bdd0b03d5549
+  languageName: node
+  linkType: hard
+
 "yauzl@npm:^3.2.1":
   version: 3.4.0
   resolution: "yauzl@npm:3.4.0"

From 2e7df1ec7d333e1d74203bee65e26506b602fd57 Mon Sep 17 00:00:00 2001
From: Flop Butylkin <flopspm@gmail.com>
Date: Mon, 6 Jul 2026 00:39:02 +0200
Subject: [PATCH 4/4] fix(pdf): render bank account details & fix NaN QR
 verification date

The invoice PDF renderer dropped bank account data entirely and emitted a QR
verification URL with a NaN date: the payment due date and issue date were
bound to the wrong XML paths, the payment-form code was left raw, and bank
details were never modeled at all.

- Add a bank-account repeater to the payment block (account number, SWIFT,
  bank name), rendered as localized label:value lines; skip empty optional
  payment fields.
- Bind the payment due date to the payment-term element and decode the
  payment-form code to its name.
- Read the QR issue date from Fa/P_1 (not the document root) and guard the
  verification-link service against an unparseable date instead of emitting a
  NaN segment.
- Rebuild the FA(2)/FA(3) fixtures from a realistic payment structure so the
  strict self-consistency test exercises the payment/bank paths, and add tests
  for the QR date, the payment-form formatter, and bank-account rendering.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EaMDwzgFf8zzWn7mM1Tjq5
---
 packages/ksef-client-ts/src/pdf/format.ts     |  25 ++++-
 packages/ksef-client-ts/src/pdf/i18n/en.ts    |   4 +
 packages/ksef-client-ts/src/pdf/i18n/pl.ts    |   4 +
 packages/ksef-client-ts/src/pdf/qr.ts         |  11 +-
 .../src/pdf/template/blocks/payment.ts        |  38 +++++--
 .../src/pdf/template/builtin/fa2-default.json |  15 ++-
 .../src/pdf/template/builtin/fa3-default.json |  15 ++-
 .../ksef-client-ts/src/pdf/template/dsl.ts    |  23 +++-
 .../src/qr/verification-link-service.ts       |   5 +
 .../ksef-client-ts/tests/fixtures/pdf/fa2.xml |   9 +-
 .../ksef-client-ts/tests/fixtures/pdf/fa3.xml |   9 +-
 .../tests/unit/pdf/blocks-semantic.test.ts    | 102 ++++++++++++++++++
 .../tests/unit/pdf/format.test.ts             |  22 ++++
 .../ksef-client-ts/tests/unit/pdf/qr.test.ts  |  18 +++-
 .../unit/qr/verification-link-service.test.ts |   5 +
 15 files changed, 283 insertions(+), 22 deletions(-)

diff --git a/packages/ksef-client-ts/src/pdf/format.ts b/packages/ksef-client-ts/src/pdf/format.ts
index f27a095..a69b34d 100644
--- a/packages/ksef-client-ts/src/pdf/format.ts
+++ b/packages/ksef-client-ts/src/pdf/format.ts
@@ -1,9 +1,9 @@
 /**
  * Value formatters referenced by DSL bindings (`format: 'money' | 'date' |
- * 'number' | 'nip'`). Each is total: on unparseable input it returns the raw
- * string unchanged, so a formatter never throws mid-render.
+ * 'number' | 'nip' | 'paymentForm'`). Each is total: on unparseable input it
+ * returns the raw string unchanged, so a formatter never throws mid-render.
  */
-export type FormatterName = 'money' | 'date' | 'number' | 'nip';
+export type FormatterName = 'money' | 'date' | 'number' | 'nip' | 'paymentForm';
 
 const NBSP = ' ';
 
@@ -47,11 +47,30 @@ export function formatNip(raw: string): string {
   return `${digits.slice(0, 3)}-${digits.slice(3, 6)}-${digits.slice(6, 8)}-${digits.slice(8, 10)}`;
 }
 
+/**
+ * KSeF `FormaPlatnosci` enum code → Polish label (the codes are a Polish fiscal
+ * enum, so the decoded name is Polish regardless of the render locale, matching
+ * how the official visualizations print it). An unknown code passes through.
+ */
+const PAYMENT_FORMS: Record<string, string> = {
+  '1': 'Gotówka',
+  '2': 'Karta',
+  '3': 'Bon',
+  '4': 'Czek',
+  '5': 'Kredyt',
+  '6': 'Przelew',
+  '7': 'Mobilna',
+};
+export function formatPaymentForm(raw: string): string {
+  return PAYMENT_FORMS[raw.trim()] ?? raw;
+}
+
 const FORMATTERS: Record<FormatterName, (raw: string) => string> = {
   money: formatMoney,
   date: formatDate,
   number: formatNumber,
   nip: formatNip,
+  paymentForm: formatPaymentForm,
 };
 
 /** Apply a named formatter; an unknown name returns the value unchanged. */
diff --git a/packages/ksef-client-ts/src/pdf/i18n/en.ts b/packages/ksef-client-ts/src/pdf/i18n/en.ts
index 15cf318..50701aa 100644
--- a/packages/ksef-client-ts/src/pdf/i18n/en.ts
+++ b/packages/ksef-client-ts/src/pdf/i18n/en.ts
@@ -26,6 +26,10 @@ export const en: LabelBundle = {
   paid: 'Paid',
   paymentDate: 'Payment due',
   paymentMethod: 'Payment method',
+  bankAccounts: 'Bank account',
+  bankAccount: 'Account number',
+  swift: 'SWIFT / BIC',
+  bankName: 'Bank name',
   annotations: 'Annotations',
   upoTitle: 'Official Receipt Confirmation (UPO)',
   ksefDocNumber: 'KSeF document number',
diff --git a/packages/ksef-client-ts/src/pdf/i18n/pl.ts b/packages/ksef-client-ts/src/pdf/i18n/pl.ts
index 197246f..f8c3ba2 100644
--- a/packages/ksef-client-ts/src/pdf/i18n/pl.ts
+++ b/packages/ksef-client-ts/src/pdf/i18n/pl.ts
@@ -29,6 +29,10 @@ export const pl: LabelBundle = {
   paid: 'Zapłacono',
   paymentDate: 'Termin płatności',
   paymentMethod: 'Forma płatności',
+  bankAccounts: 'Rachunek bankowy',
+  bankAccount: 'Numer rachunku',
+  swift: 'Kod SWIFT',
+  bankName: 'Nazwa banku',
   // annotations
   annotations: 'Adnotacje',
   // upo
diff --git a/packages/ksef-client-ts/src/pdf/qr.ts b/packages/ksef-client-ts/src/pdf/qr.ts
index 5d79c29..a06d2c1 100644
--- a/packages/ksef-client-ts/src/pdf/qr.ts
+++ b/packages/ksef-client-ts/src/pdf/qr.ts
@@ -12,6 +12,7 @@ import crypto from 'node:crypto';
 import { VerificationLinkService } from '../qr/verification-link-service.js';
 import { Environment } from '../config/environments.js';
 import { get } from './accessor.js';
+import { KSeFPdfError } from './errors.js';
 
 /**
  * SHA-256 over the raw invoice bytes, returned as standard base64.
@@ -65,7 +66,15 @@ export interface DeriveInvoiceQrUrlParams {
  */
 export function deriveInvoiceQrUrl(params: DeriveInvoiceQrUrlParams): string {
   const nip = get(params.body, 'Podmiot1.DaneIdentyfikacyjne.NIP', params.strict);
-  const issueDate = get(params.body, 'P_1', params.strict);
+  // Issue date lives at Faktura/Fa/P_1 — the invoice-line group `Fa`, not the
+  // document root (where Podmiot1 sits). Reading it at the root yields '' and a
+  // NaN-NaN-NaN date segment in the URL.
+  const issueDate = get(params.body, 'Fa.P_1', params.strict);
+  if (issueDate === '') {
+    throw new KSeFPdfError(
+      'Cannot build the QR verification URL: issue date (Fa/P_1) is missing from the invoice.',
+    );
+  }
   const hash = params.invoiceHash ?? computeInvoiceHashBase64(params.rawInput);
   const base = resolveBaseQrUrl(params.env, params.baseQrUrl);
   return new VerificationLinkService(base).buildInvoiceVerificationUrl(nip, issueDate, hash);
diff --git a/packages/ksef-client-ts/src/pdf/template/blocks/payment.ts b/packages/ksef-client-ts/src/pdf/template/blocks/payment.ts
index e5bf859..2f18587 100644
--- a/packages/ksef-client-ts/src/pdf/template/blocks/payment.ts
+++ b/packages/ksef-client-ts/src/pdf/template/blocks/payment.ts
@@ -1,19 +1,43 @@
+import { get, list } from '../../accessor.js';
 import { applyFormat } from '../../format.js';
 import type { PaymentBlock } from '../dsl.js';
 import { resolveBinding, type BlockRenderer, type PdfNode } from '../interpret.js';
 
 /**
- * Payment details: a `payment` heading followed by one `label: value` line per
- * {@link PaymentBlock.rows} entry (localized label + formatted scalar binding).
- * Visibility (`when`) is resolved centrally by the interpreter, so this renderer
- * always emits its content.
+ * Payment details: a `payment` heading, one `label: value` line per
+ * {@link PaymentBlock.rows} entry, then an optional repeating bank-account
+ * section ({@link PaymentBlock.accounts}) — one `label: value` line per field,
+ * for each account in the collection.
+ *
+ * A row/field whose value resolves empty is skipped, so absent optional fields
+ * (KSeF invoices carry many) don't print a dangling "Label:" with no value.
+ * Strict mode still surfaces dot-path typos: a *missing* binding throws before
+ * it can be skipped, so a self-consistency fixture that populates every path
+ * catches template mistakes. Visibility (`when`) is resolved centrally by the
+ * interpreter, so this renderer always emits its content.
  */
 export const paymentRenderer: BlockRenderer<PaymentBlock> = (block, ctx) => {
   const stack: PdfNode[] = [{ text: ctx.label('payment'), style: 'h2' }];
+
   for (const row of block.rows) {
-    stack.push({
-      text: `${ctx.label(row.label)}: ${applyFormat(resolveBinding(row.path, ctx), row.format)}`,
-    });
+    const value = applyFormat(resolveBinding(row.path, ctx), row.format);
+    if (value === '') continue;
+    stack.push({ text: `${ctx.label(row.label)}: ${value}` });
+  }
+
+  if (block.accounts) {
+    const lines: PdfNode[] = [];
+    for (const account of list(ctx.root, block.accounts.from)) {
+      for (const field of block.accounts.fields) {
+        const value = applyFormat(get(account, field.path, ctx.strict), field.format);
+        if (value === '') continue;
+        lines.push({ text: `${ctx.label(field.label)}: ${value}` });
+      }
+    }
+    if (lines.length > 0) {
+      if (block.accounts.heading) stack.push({ text: ctx.label(block.accounts.heading), style: 'h2' });
+      stack.push(...lines);
+    }
   }
 
   return {
diff --git a/packages/ksef-client-ts/src/pdf/template/builtin/fa2-default.json b/packages/ksef-client-ts/src/pdf/template/builtin/fa2-default.json
index d58373d..534d98f 100644
--- a/packages/ksef-client-ts/src/pdf/template/builtin/fa2-default.json
+++ b/packages/ksef-client-ts/src/pdf/template/builtin/fa2-default.json
@@ -71,9 +71,18 @@
       "when": "Fa.Platnosc",
       "rows": [
         { "label": "paid", "path": "Fa.Platnosc.Zaplacono" },
-        { "label": "paymentDate", "path": "Fa.Platnosc.DataZaplaty", "format": "date" },
-        { "label": "paymentMethod", "path": "Fa.Platnosc.FormaPlatnosci" }
-      ]
+        { "label": "paymentDate", "path": "Fa.Platnosc.TerminPlatnosci.Termin", "format": "date" },
+        { "label": "paymentMethod", "path": "Fa.Platnosc.FormaPlatnosci", "format": "paymentForm" }
+      ],
+      "accounts": {
+        "from": "Fa.Platnosc.RachunekBankowy",
+        "heading": "bankAccounts",
+        "fields": [
+          { "label": "bankAccount", "path": "NrRB" },
+          { "label": "swift", "path": "SWIFT" },
+          { "label": "bankName", "path": "NazwaBanku" }
+        ]
+      }
     },
     { "type": "qr", "when": "qr", "fit": 90 },
     { "type": "footer", "text": "ksef-client-ts", "style": "footerNote" }
diff --git a/packages/ksef-client-ts/src/pdf/template/builtin/fa3-default.json b/packages/ksef-client-ts/src/pdf/template/builtin/fa3-default.json
index 99a93c0..a8ee41d 100644
--- a/packages/ksef-client-ts/src/pdf/template/builtin/fa3-default.json
+++ b/packages/ksef-client-ts/src/pdf/template/builtin/fa3-default.json
@@ -71,9 +71,18 @@
       "when": "Fa.Platnosc",
       "rows": [
         { "label": "paid", "path": "Fa.Platnosc.Zaplacono" },
-        { "label": "paymentDate", "path": "Fa.Platnosc.DataZaplaty", "format": "date" },
-        { "label": "paymentMethod", "path": "Fa.Platnosc.FormaPlatnosci" }
-      ]
+        { "label": "paymentDate", "path": "Fa.Platnosc.TerminPlatnosci.Termin", "format": "date" },
+        { "label": "paymentMethod", "path": "Fa.Platnosc.FormaPlatnosci", "format": "paymentForm" }
+      ],
+      "accounts": {
+        "from": "Fa.Platnosc.RachunekBankowy",
+        "heading": "bankAccounts",
+        "fields": [
+          { "label": "bankAccount", "path": "NrRB" },
+          { "label": "swift", "path": "SWIFT" },
+          { "label": "bankName", "path": "NazwaBanku" }
+        ]
+      }
     },
     { "type": "qr", "when": "qr", "fit": 90 },
     { "type": "footer", "text": "ksef-client-ts", "style": "footerNote" }
diff --git a/packages/ksef-client-ts/src/pdf/template/dsl.ts b/packages/ksef-client-ts/src/pdf/template/dsl.ts
index bbf7a87..4ebeb4a 100644
--- a/packages/ksef-client-ts/src/pdf/template/dsl.ts
+++ b/packages/ksef-client-ts/src/pdf/template/dsl.ts
@@ -72,10 +72,23 @@ export interface TotalsBlock {
   style?: string;
 }
 
+/**
+ * A repeating group of bank-account fields under a payment block. `from` names
+ * the account collection (read as an always-array), `fields` are the per-account
+ * label:value lines, and `heading` is an optional i18n sub-heading printed once
+ * when at least one account resolves.
+ */
+export interface PaymentAccounts {
+  from: string;
+  heading?: string;
+  fields: FieldDef[];
+}
+
 export interface PaymentBlock {
   type: 'payment';
   when?: string;
   rows: FieldDef[];
+  accounts?: PaymentAccounts;
   style?: string;
 }
 
@@ -183,7 +196,7 @@ export interface InvoiceTemplate {
 
 // ── zod validation ─────────────────────────────────────────────────────────
 
-const formatEnum = z.enum(['money', 'date', 'number', 'nip']);
+const formatEnum = z.enum(['money', 'date', 'number', 'nip', 'paymentForm']);
 const styleValue = z.union([z.string(), z.number(), z.boolean(), z.array(z.number())]);
 const styleSchema = z.record(z.string(), styleValue);
 const labelRef = z.object({ label: z.string().optional(), text: z.string().optional() }).strict();
@@ -224,6 +237,14 @@ const blockSchema: z.ZodType<Block> = z.lazy(() =>
       type: z.literal('payment'),
       when: z.string().optional(),
       rows: z.array(fieldDef),
+      accounts: z
+        .object({
+          from: z.string(),
+          heading: z.string().optional(),
+          fields: z.array(fieldDef),
+        })
+        .strict()
+        .optional(),
       style: z.string().optional(),
     }).strict(),
     z.object({ type: z.literal('annotations'), fields: z.array(fieldDef), style: z.string().optional() }).strict(),
diff --git a/packages/ksef-client-ts/src/qr/verification-link-service.ts b/packages/ksef-client-ts/src/qr/verification-link-service.ts
index 981da99..eb4dfec 100644
--- a/packages/ksef-client-ts/src/qr/verification-link-service.ts
+++ b/packages/ksef-client-ts/src/qr/verification-link-service.ts
@@ -13,6 +13,11 @@ export class VerificationLinkService {
     invoiceHashBase64: string,
   ): string {
     const date = typeof issueDate === 'string' ? new Date(issueDate) : issueDate;
+    if (Number.isNaN(date.getTime())) {
+      throw new Error(
+        `Invalid issueDate for verification URL: ${JSON.stringify(issueDate)} (expected a parseable date, e.g. "2026-06-08").`,
+      );
+    }
     const dd = String(date.getUTCDate()).padStart(2, '0');
     const mm = String(date.getUTCMonth() + 1).padStart(2, '0');
     const yyyy = date.getUTCFullYear();
diff --git a/packages/ksef-client-ts/tests/fixtures/pdf/fa2.xml b/packages/ksef-client-ts/tests/fixtures/pdf/fa2.xml
index 2e03abd..e2baef6 100644
--- a/packages/ksef-client-ts/tests/fixtures/pdf/fa2.xml
+++ b/packages/ksef-client-ts/tests/fixtures/pdf/fa2.xml
@@ -68,8 +68,15 @@
         </FaWiersz>
         <Platnosc>
             <Zaplacono>1</Zaplacono>
-            <DataZaplaty>2025-01-15</DataZaplaty>
+            <TerminPlatnosci>
+                <Termin>2025-02-01</Termin>
+            </TerminPlatnosci>
             <FormaPlatnosci>6</FormaPlatnosci>
+            <RachunekBankowy>
+                <NrRB>11109000880000000100000001</NrRB>
+                <SWIFT>WBKPPLPP</SWIFT>
+                <NazwaBanku>Bank Przykładowy S.A.</NazwaBanku>
+            </RachunekBankowy>
         </Platnosc>
     </Fa>
 </Faktura>
diff --git a/packages/ksef-client-ts/tests/fixtures/pdf/fa3.xml b/packages/ksef-client-ts/tests/fixtures/pdf/fa3.xml
index b19d3cd..ee99bfe 100644
--- a/packages/ksef-client-ts/tests/fixtures/pdf/fa3.xml
+++ b/packages/ksef-client-ts/tests/fixtures/pdf/fa3.xml
@@ -68,8 +68,15 @@
         </FaWiersz>
         <Platnosc>
             <Zaplacono>1</Zaplacono>
-            <DataZaplaty>2025-01-15</DataZaplaty>
+            <TerminPlatnosci>
+                <Termin>2025-02-01</Termin>
+            </TerminPlatnosci>
             <FormaPlatnosci>6</FormaPlatnosci>
+            <RachunekBankowy>
+                <NrRB>11109000880000000100000001</NrRB>
+                <SWIFT>WBKPPLPP</SWIFT>
+                <NazwaBanku>Bank Przykładowy S.A.</NazwaBanku>
+            </RachunekBankowy>
         </Platnosc>
     </Fa>
 </Faktura>
diff --git a/packages/ksef-client-ts/tests/unit/pdf/blocks-semantic.test.ts b/packages/ksef-client-ts/tests/unit/pdf/blocks-semantic.test.ts
index 444e461..d37466b 100644
--- a/packages/ksef-client-ts/tests/unit/pdf/blocks-semantic.test.ts
+++ b/packages/ksef-client-ts/tests/unit/pdf/blocks-semantic.test.ts
@@ -322,6 +322,108 @@ describe('paymentRenderer', () => {
     expect(node.stack[0].text).toBe('payment');
     expect('style' in node).toBe(false);
   });
+
+  it('skips rows whose value resolves empty (absent optional field)', () => {
+    const ctx = makeCtx({ Fa: { FormaPlatnosci: '6' } });
+    const node = rec(
+      paymentRenderer(
+        {
+          type: 'payment',
+          rows: [
+            { label: 'paid', path: 'Fa.Zaplacono' }, // absent → skipped
+            { label: 'paymentMethod', path: 'Fa.FormaPlatnosci', format: 'paymentForm' },
+          ],
+        },
+        ctx,
+        noRender,
+      ),
+    );
+    expect(node.stack).toHaveLength(2); // heading + only the present row
+    expect(node.stack[1].text).toBe('paymentMethod: Przelew');
+  });
+
+  it('renders a bank-account repeater: heading + one label:value line per field, per account', () => {
+    const ctx = makeCtx({
+      Fa: {
+        Platnosc: {
+          RachunekBankowy: [
+            { NrRB: '11109000880000000100000001', SWIFT: 'WBKPPLPP', NazwaBanku: 'Bank A' },
+            { NrRB: '22109000880000000100000002', NazwaBanku: 'Bank B' }, // no SWIFT → skipped
+          ],
+        },
+      },
+    });
+    const node = rec(
+      paymentRenderer(
+        {
+          type: 'payment',
+          rows: [],
+          accounts: {
+            from: 'Fa.Platnosc.RachunekBankowy',
+            heading: 'bankAccounts',
+            fields: [
+              { label: 'bankAccount', path: 'NrRB' },
+              { label: 'swift', path: 'SWIFT' },
+              { label: 'bankName', path: 'NazwaBanku' },
+            ],
+          },
+        },
+        ctx,
+        noRender,
+      ),
+    );
+    // heading(payment) + heading(bankAccounts) + [acc1: 3 lines] + [acc2: 2 lines]
+    expect(node.stack).toHaveLength(7);
+    expect(node.stack[1].text).toBe('bankAccounts');
+    expect(node.stack[1].style).toBe('h2');
+    expect(node.stack[2].text).toBe('bankAccount: 11109000880000000100000001');
+    expect(node.stack[3].text).toBe('swift: WBKPPLPP');
+    expect(node.stack[4].text).toBe('bankName: Bank A');
+    // second account skipped its empty SWIFT
+    expect(node.stack[5].text).toBe('bankAccount: 22109000880000000100000002');
+    expect(node.stack[6].text).toBe('bankName: Bank B');
+  });
+
+  it('omits the accounts section entirely when the collection is absent', () => {
+    const node = rec(
+      paymentRenderer(
+        {
+          type: 'payment',
+          rows: [{ label: 'paymentMethod', path: 'Fa.Platnosc.FormaPlatnosci', format: 'paymentForm' }],
+          accounts: {
+            from: 'Fa.Platnosc.RachunekBankowy',
+            heading: 'bankAccounts',
+            fields: [{ label: 'bankAccount', path: 'NrRB' }],
+          },
+        },
+        makeCtx({ Fa: { Platnosc: { FormaPlatnosci: '6' } } }),
+        noRender,
+      ),
+    );
+    expect(node.stack).toHaveLength(2); // heading + the one payment row, no bank heading
+    expect(node.stack[1].text).toBe('paymentMethod: Przelew');
+  });
+
+  it('throws in strict mode on a missing bank-account field binding', () => {
+    const ctx = makeCtx(
+      { Fa: { Platnosc: { RachunekBankowy: { NrRB: '111' } } } },
+      { strict: true },
+    );
+    expect(() =>
+      paymentRenderer(
+        {
+          type: 'payment',
+          rows: [],
+          accounts: {
+            from: 'Fa.Platnosc.RachunekBankowy',
+            fields: [{ label: 'swift', path: 'SWIFT' }], // absent in the account → strict throws
+          },
+        },
+        ctx,
+        noRender,
+      ),
+    ).toThrow(/Missing binding/);
+  });
 });
 
 // ── annotations ─────────────────────────────────────────────────────────────
diff --git a/packages/ksef-client-ts/tests/unit/pdf/format.test.ts b/packages/ksef-client-ts/tests/unit/pdf/format.test.ts
index 1c8f7e3..c83b382 100644
--- a/packages/ksef-client-ts/tests/unit/pdf/format.test.ts
+++ b/packages/ksef-client-ts/tests/unit/pdf/format.test.ts
@@ -4,6 +4,7 @@ import {
   formatNumber,
   formatDate,
   formatNip,
+  formatPaymentForm,
   applyFormat,
 } from '../../../src/pdf/format.js';
 
@@ -89,6 +90,23 @@ describe('formatNip', () => {
   });
 });
 
+describe('formatPaymentForm', () => {
+  it('decodes each known FormaPlatnosci code to its Polish label', () => {
+    expect(formatPaymentForm('1')).toBe('Gotówka');
+    expect(formatPaymentForm('6')).toBe('Przelew');
+    expect(formatPaymentForm('7')).toBe('Mobilna');
+  });
+
+  it('tolerates surrounding whitespace', () => {
+    expect(formatPaymentForm(' 6 ')).toBe('Przelew');
+  });
+
+  it('passes an unknown code through unchanged', () => {
+    expect(formatPaymentForm('99')).toBe('99');
+    expect(formatPaymentForm('')).toBe('');
+  });
+});
+
 describe('applyFormat', () => {
   it('returns the value unchanged when no formatter is named', () => {
     expect(applyFormat('1234.5', undefined)).toBe('1234.5');
@@ -114,4 +132,8 @@ describe('applyFormat', () => {
   it('routes to the nip formatter', () => {
     expect(applyFormat('5213003700', 'nip')).toBe('521-300-37-00');
   });
+
+  it('routes to the paymentForm formatter', () => {
+    expect(applyFormat('6', 'paymentForm')).toBe('Przelew');
+  });
 });
diff --git a/packages/ksef-client-ts/tests/unit/pdf/qr.test.ts b/packages/ksef-client-ts/tests/unit/pdf/qr.test.ts
index de89564..8cd9753 100644
--- a/packages/ksef-client-ts/tests/unit/pdf/qr.test.ts
+++ b/packages/ksef-client-ts/tests/unit/pdf/qr.test.ts
@@ -11,8 +11,11 @@ import { Environment } from '../../../src/config/environments.js';
 import type { RenderContext } from '../../../src/pdf/template/interpret.js';
 import type { QrBlock } from '../../../src/pdf/template/dsl.js';
 
-/** Minimal parsed body: seller NIP + issue date, same shape as ctx.root. */
-const body = { Podmiot1: { DaneIdentyfikacyjne: { NIP: '5213003700' } }, P_1: '2025-01-15' };
+/**
+ * Minimal parsed body: seller NIP at the document root, issue date under `Fa`
+ * (P_1 lives at Faktura/Fa/P_1, NOT the root) — the real parsed-Faktura shape.
+ */
+const body = { Podmiot1: { DaneIdentyfikacyjne: { NIP: '5213003700' } }, Fa: { P_1: '2025-01-15' } };
 
 // A clean UTF-8 invoice payload with LF newlines and no BOM.
 const CLEAN = '<Faktura>\n<P_2>FV/1</P_2>\n</Faktura>';
@@ -109,6 +112,17 @@ describe('deriveInvoiceQrUrl', () => {
   it('passes strict through to the accessor (throws on a missing binding)', () => {
     expect(() => deriveInvoiceQrUrl({ rawInput: CLEAN, body: {}, strict: true })).toThrow();
   });
+
+  it('embeds a real DD-MM-YYYY issue date read from Fa/P_1 (regression: not NaN-NaN-NaN)', () => {
+    const url = deriveInvoiceQrUrl({ rawInput: CLEAN, body, env: 'prod' });
+    expect(url).toContain('/invoice/5213003700/15-01-2025/');
+    expect(url).not.toContain('NaN');
+  });
+
+  it('throws a clear error when the issue date is absent (never emits a NaN date)', () => {
+    const noDate = { Podmiot1: { DaneIdentyfikacyjne: { NIP: '5213003700' } } };
+    expect(() => deriveInvoiceQrUrl({ rawInput: CLEAN, body: noDate })).toThrow(/issue date/i);
+  });
 });
 
 describe('qrRenderer', () => {
diff --git a/packages/ksef-client-ts/tests/unit/qr/verification-link-service.test.ts b/packages/ksef-client-ts/tests/unit/qr/verification-link-service.test.ts
index b1382dd..44081d5 100644
--- a/packages/ksef-client-ts/tests/unit/qr/verification-link-service.test.ts
+++ b/packages/ksef-client-ts/tests/unit/qr/verification-link-service.test.ts
@@ -31,6 +31,11 @@ describe('VerificationLinkService', () => {
       expect(url).toMatch(/\/05-12-2024\//);
     });
 
+    it('throws on an unparseable date instead of emitting a NaN-NaN-NaN segment', () => {
+      expect(() => service.buildInvoiceVerificationUrl(nip, '', hash)).toThrow(/Invalid issueDate/);
+      expect(() => service.buildInvoiceVerificationUrl(nip, 'not-a-date', hash)).toThrow(/Invalid issueDate/);
+    });
+
     it('should use Base64URL encoding without padding', () => {
       const url = service.buildInvoiceVerificationUrl(nip, '2024-01-01T00:00:00Z', hash);