oh-my-agent-commandcode 0.0.0-stage → 20.38.3

package/skills/oma-frontend/resources/tech-stack.md

@@ -0,0 +1,156 @@
+# Frontend Agent - Tech Stack Reference
+
+These are defaults for new projects without an established stack. Preserve the target project's installed versions and conventions; a scoped feature or fix does not authorize a stack migration.
+
+## Core Framework
+- **Framework**: Next.js 16+ (App Router), React 19+
+- **Language**: TypeScript (strict mode)
+- **Testing**: Vitest, React Testing Library
+- **Browser verification**: Browser verification uses the installed MCPs selected in `mcp.devtools_browsers`: Aside (`aside`, default), Chrome DevTools MCP (`chrome`), and Firefox DevTools MCP (`firefox`). Multiple selections are supported; use `oma update mcp` to change them. Discover the selected server’s actual tools before use; tool names and capabilities differ between servers. An empty selection disables browser MCP verification; report any unverified UI checks.
+- **UI**: `shadcn/ui` on the **Base UI** engine (see below)
+
+## shadcn/ui Primitive Engine — Base UI vs Radix
+
+shadcn/ui ships on two interchangeable headless engines: **Radix UI** and **Base UI**
+(by the MUI team). They provide similar component categories, but primitive and
+wrapper APIs differ. Verify composition, props and accessibility before migration.
+
+### How the engine is selected
+
+The engine is **not** a standalone `components.json` field. It is encoded in the **`style`**
+prefix:
+
+| `style` value | Engine |
+|---|---|
+| `base-*` (e.g. `base-vega`) | **Base UI** |
+| `radix-*` (e.g. `radix-nova`) | Radix UI |
+
+```jsonc
+// components.json
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "base-vega",        // <- engine + style; base-* = Base UI
+  "rsc": true,
+  "tsx": true,
+  "tailwind": { "css": "src/styles/globals.css", "baseColor": "neutral", "cssVariables": true },
+  "iconLibrary": "lucide",
+  "aliases": { /* ... */ }
+}
+```
+
+Bootstrap with `npx shadcn create` (prompts for the engine) or `npx shadcn init`.
+
+### Project default: **Base UI**
+
+1. For a new project without an engine choice, Base UI is an available default. Verify the components and integration required by the project.
+2. **Radix is an allowed fallback** — keep `radix-*` for an existing Radix codebase, or when a
+   needed component is only stable on Radix. State the reason when choosing Radix.
+3. **Do NOT big-bang migrate** an existing project to Base UI just because it is the default.
+   Migrate component-by-component, with reason; due to API differences a global swap is risky.
+4. To switch engines: change the `style` prefix, then re-add base components with
+   `npx shadcn add button card dialog … --overwrite`. Treat `components/ui/*` as read-only
+   otherwise (customize via wrappers / `cva`).
+
+## Next.js 16 Conventions
+
+### Proxy replaces Middleware
+
+For projects using the Next.js 16+ proxy convention, preserve `proxy.ts`. Check the installed framework version and existing routing before proposing a migration.
+
+- File: `middleware.ts` → `proxy.ts` (root or `src/`)
+- Exported function: `middleware` → `proxy`
+- Config flags: `skipMiddlewareUrlNormalize` → `skipProxyUrlNormalize`, etc.
+<!-- oma-docs:ignore-start -->
+- `src/proxy.ts` is the canonical request-proxy / auth-gate location
+<!-- oma-docs:ignore-end -->
+
+Do not infer that a framework entry point is unused from missing imports alone. Verify its location, exports, configuration, and relevant tests before reporting a wiring defect.
+
+Reference: https://nextjs.org/docs/messages/middleware-to-proxy
+
+### React Compiler (stable in Next.js 16)
+
+Next.js 16 supports the React Compiler as a **stable, opt-in** top-level option (disabled by
+default). It auto-memoizes components, replacing most manual memoization.
+
+```ts
+// next.config.ts (requires `babel-plugin-react-compiler` as a devDependency)
+const nextConfig: NextConfig = {
+  reactCompiler: true, // or { compilationMode: 'annotation' } for opt-in per component
+}
+```
+
+Rules:
+
+1. **Check whether the project has it enabled before tuning renders.** Look for
+   `reactCompiler` in `next.config.*`.
+2. **Compiler ON**: do NOT hand-write `useMemo` / `useCallback` / `React.memo` in new code;
+   the compiler owns memoization. Correct `useEffect` deps still matter (the compiler does
+   not fix dependency bugs).
+3. **Compiler OFF**: memoize manually as usual; suggest enabling the compiler only as a
+   separate, explicit change (it adds Babel to the build and increases compile times).
+4. Do not mix modes ad hoc: `'annotation'` mode means only `"use memo"`-annotated components
+   compile; don't assume whole-app coverage.
+
+## Server State — orval-generated TanStack Query hooks
+
+When the project has an OpenAPI spec (most oma projects do), **TanStack Query hooks are
+generated by `orval`, not hand-written**. The pipeline lives in oma-dev-workflow
+(`resources/api-workflows.md`): backend emits `openapi.json` → `bunx orval` (usually via
+`mise run gen:api`) emits typed `useQuery`/`useMutation` hooks (`client: react-query`).
+
+1. **Generated output is read-only**, same rule as `components/ui/*`. Never edit generated
+   hooks/models; fix the OpenAPI spec (or orval config) and regenerate.
+2. **Contract change flow**: backend schema change → regenerate spec → `bunx orval` →
+   fix resulting type errors in consuming code. Don't patch types by hand to "match later".
+3. **Cross-cutting concerns go in the orval `mutator`** (custom axios/fetch instance):
+   auth headers, base URL, error normalization; never per-hook.
+4. **Hand-written TanStack Query hooks are the exception**: third-party APIs or endpoints
+   outside the spec. Follow the fallback pattern in `snippets.md` §TanStack Query Hook.
+
+## Mutations — Server Actions vs TanStack Query
+
+Both are legitimate write paths in Next.js 16; pick per mutation, and don't route the same
+mutation through both.
+
+| Pick | When |
+|---|---|
+| **Server Action** (`'use server'` + `useActionState`) | Form-shaped, page-scoped writes where progressive enhancement or zero client JS matters; simple submit → revalidate flows (`revalidatePath` / `revalidateTag`); no shared client cache to update. |
+| **TanStack Query mutation** | The write must update client-cached reads (`invalidateQueries`, optimistic updates, rollback); fires outside a form (drag-drop, toggles, autosave); needs retry/queue/offline semantics or fine-grained pending UI across components. |
+
+Guidance:
+
+1. If the data is already read through TanStack Query, mutate through TanStack Query; a
+   Server Action won't invalidate the client cache by itself.
+2. Server Actions are still server endpoints: validate input with zod on the server side and
+   enforce auth inside the action, never only in the UI.
+3. Don't call Server Actions from TanStack Query's `mutationFn` as a default pattern; that
+   stacks two mutation layers. Choose one owner per mutation.
+
+## Client State — Jotai vs Zustand
+
+Client state has **no project default**; pick per intent. Both are allowed, but **only one
+per project** unless there is a strong reason to mix. The overriding rule is to *minimize
+client state* in the first place: server state belongs in **TanStack Query**, URL state in
+**nuqs**. Reach for a client-state library only for genuine client-owned state.
+
+| Pick | When |
+|---|---|
+| **Jotai** | Atomic / bottom-up. Fine-grained, derived, or near-local shared state; many small independent atoms; state that maps onto React's render graph and RSC-split boundaries. |
+| **Zustand** | Store / top-down. A single cohesive global store with action methods; needs non-React access (`store.getState()` / `subscribe` outside render); simpler mental model for app-wide state. |
+
+Guidance:
+
+1. **State the choice** in the project (e.g. a short note in the app README or DESIGN.md) so
+   contributors don't introduce the other library ad hoc.
+2. **Don't mix** Jotai and Zustand in one app without justification — two client-state models
+   fragment the codebase.
+3. **Default-free does not mean optional analysis**: if neither atomic nor single-store clearly
+   fits, the state probably belongs in TanStack Query (server) or nuqs (URL), not here.
+
+## Optional Serena examples
+
+These examples apply only when Serena is the configured provider and its tools are available. Otherwise use the project-selected provider or native search under the shared code-intelligence contract.
+- `find_symbol("ComponentName")`: locate existing component
+- `get_symbols_overview("src/components")`: list all components
+- `find_referencing_symbols("Button")`: find usages before changes

package/skills/oma-hwp/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: oma-hwp
+description: Convert Hangul HWP, HWPX, or HWPML documents to Markdown with
+  kordoc. Use for text, table, and image extraction from these formats.
+---
+
+# HWP Skill - HWP / HWPX / HWPML to Markdown Conversion
+
+## Scheduling
+
+### Goal
+Convert Korean HWP-family documents into readable Markdown or structured JSON while preserving document structure for LLM context, RAG, government-document review, or enterprise document processing.
+
+### Intent signature
+- User asks to convert, parse, read, extract, or transform `.hwp`, `.hwpx`, or `.hwpml`.
+- User mentions Korean word processor files, Hangul documents, government forms, or "한글 파일".
+- User needs headings, tables, nested tables, lists, images, footnotes, or hyperlinks extracted from HWP-family files.
+
+### When to use
+- Converting Korean HWP documents (`.hwp`, `.hwpx`, `.hwpml`) to Markdown
+- Preparing Korean government/enterprise documents for LLM context or RAG
+- Extracting structured content (tables, headings, lists, images) from HWP
+- User says "convert this HWP", "parse hwpx", "HWP to markdown", "한글 파일"
+
+### When NOT to use
+- PDF files -> use `oma-pdf` (OCR + Tagged PDF specialization)
+- XLSX / DOCX files -> out of scope; run `bunx kordoc` directly if needed (note: `oma-docs` is the documentation-drift skill, not a converter)
+- Generating or editing HWP documents -> out of scope (kordoc itself supports `generate` / `fill` / `seal` / `patch` / `redact` / `lint` / `validate` / `render` subcommands; run `bunx kordoc@latest <subcommand>` directly if needed)
+- Already-text files -> use Read tool directly
+
+### Expected inputs
+- `input_path`: `.hwp`, `.hwpx`, or `.hwpml` file path
+- `output_path` or `output_dir`: optional explicit output target
+- `format`: optional output format — `markdown` (default), `json` (structured AST), or `chunks` (RAG-oriented structural chunk JSON with heading breadcrumbs and standalone table chunks)
+- `page_range`: optional page or section range
+- `kordoc_version`: optional pinned kordoc version
+
+### Expected outputs
+- Markdown output next to the input file or in the requested directory
+- Optional JSON or RAG-chunks output when requested
+- Post-processed Markdown with flattened GFM tables and stripped Private Use Area glyphs by default
+- A short report with output path, detected source format, and conversion issues
+
+### Dependencies
+- `bun` and `bunx`
+- `bunx kordoc@latest` or configured pinned kordoc version
+- `resources/flatten-tables.ts` for Markdown cleanup
+- Local filesystem access to input and output paths
+
+### Control-flow features
+- Branches by file extension, output target, format, page range, encryption/DRM state, and post-processing requirements
+- Calls external CLI tools through `bunx` and `bun run`
+- Reads local HWP-family files and writes local Markdown or JSON output
+- Routes non-HWP inputs to other skills instead of stretching this skill's scope
+
+## Structural Flow
+
+### Entry
+1. Confirm the input path exists.
+2. Confirm the extension is `.hwp`, `.hwpx`, or `.hwpml`.
+3. Resolve output path or directory and default filename.
+4. Check that `bun` is available.
+
+### Scenes
+1. **PREPARE**: Validate path, extension, size, output target, and requested format.
+2. **ACQUIRE**: Detect source format and runtime availability.
+3. **ACT**: Run `kordoc` with explicit output target and requested options.
+4. **VERIFY**: Post-process Markdown and inspect structure for headings, tables, lists, images, and footnotes.
+5. **FINALIZE**: Report output path, source format, and any conversion limitations.
+
+### Transitions
+- If the input is `.pdf`, stop and route to `oma-pdf`.
+- If the input is `.xlsx` or `.docx`, explain that this skill does not advertise those formats.
+- If `bun` is unavailable, stop and ask the user to install Bun.
+- If Markdown is produced, run `resources/flatten-tables.ts` unless the caller explicitly needs HTML tables or PUA glyphs preserved.
+- If output is empty or garbled, consult `resources/troubleshooting.md`.
+
+### Failure and recovery
+| Failure | Recovery |
+|---------|----------|
+| `bun` or `bunx` unavailable | Ask user to install Bun |
+| Unsupported or mismatched format | Check extension and magic bytes, then route or stop |
+| Encrypted or DRM-locked document | Report limitation and request an accessible copy when needed |
+| Empty Markdown output | Treat as possible scanned-image content and recommend OCR outside this skill |
+| Complex merged tables | Accept flattened Markdown or HTML fallback as best effort |
+| Stale kordoc cache | Use `bunx kordoc@latest` or configured pinned version |
+| `Cannot find module "turndown"` from `flatten-tables.ts` | Run `bun install` in this skill's `resources/` directory (its `node_modules` is gitignored and absent on fresh clones) |
+
+### Exit
+- Success: output file exists and structure is readable after post-processing.
+- Partial success: output exists with explicitly reported table, glyph, encryption, or fidelity limitations.
+- Failure: no reliable output is produced and the blocking cause is reported.
+
+## Logical Operations
+
+### Actions
+| Action | SSL primitive | Evidence |
+|--------|---------------|----------|
+| Validate file path and extension | `VALIDATE` | Input preflight in execution protocol |
+| Check runtime availability | `VALIDATE` | `bun --version` |
+| Select output target and format | `SELECT` | Output behavior and config |
+| Run converter | `CALL_TOOL` | `bunx kordoc@latest` |
+| Write output artifact | `WRITE` | Markdown or JSON output |
+| Flatten tables and strip PUA glyphs | `CALL_TOOL` | `resources/flatten-tables.ts` |
+| Inspect extraction quality | `VALIDATE` | Verification step |
+| Report result | `NOTIFY` | Final user-facing summary |
+
+### Tools and instruments
+- `kordoc`: primary HWP-family conversion CLI
+- `flatten-tables.ts`: post-processing for GFM tables and Hancom PUA cleanup
+- `bun` / `bunx`: runtime and CLI executor
+
+### Canonical command path
+```bash
+bunx kordoc@latest "{input_path}" -o "{output_path}"
+# fresh clone: run `bun install` in {skill_dir}/resources/ first (node_modules is gitignored)
+bun "{skill_dir}/resources/flatten-tables.ts" "{output_path}"
+# {skill_dir} = this skill's directory: .agents/skills/oma-hwp (project mode) or ~/.agents/skills/oma-hwp (global mode)
+```
+
+For batch conversion, use an explicit output directory:
+```bash
+bunx kordoc@latest "{input_pattern}" -d "{output_dir}"
+```
+
+### Resource scope
+| Scope | Resource target |
+|-------|-----------------|
+| `LOCAL_FS` | Input HWP-family files and generated outputs |
+| `PROCESS` | `bunx kordoc` and `bun run` subprocesses |
+| `MEMORY` | Format decisions, validation notes, and final report |
+
+### Preconditions
+- Input file exists and is readable.
+- Output location is writable or can be created.
+- `bun` is installed.
+- `kordoc` can parse the document or fail with a reportable error.
+
+### Effects and side effects
+- Creates Markdown or JSON output files.
+- May flatten merged-cell tables, trading cell fidelity for Markdown compatibility.
+- Strips Private Use Area characters by default because they render as blanks without Hancom fonts.
+- Does not intentionally modify the source HWP-family document.
+
+### Guardrails
+1. Always pass `@latest` or an explicit pinned version to avoid stale `bunx` cache.
+2. Always pass an explicit output target when the user expects a file.
+3. Do not add custom security defenses around kordoc's ZIP, XML, SSRF, or XSS defenses.
+4. Report missing tables, garbled text, empty output, encrypted segments, and best-effort DRM extraction.
+5. Keep full CLI details in `resources/execution-protocol.md` and troubleshooting branches in `resources/troubleshooting.md`.
+
+### Supported Formats
+| Format | Extension | Notes |
+|--------|-----------|-------|
+| HWP 5.x binary | `.hwp` | Full support (incl. DRM-locked via kordoc's rhwp-algorithm port) |
+| HWPX | `.hwpx` | Full support incl. nested tables, merged cells |
+| HWPML | `.hwp` (XML variant) | Auto-detected by signature |
+
+> kordoc also parses PDF / XLSX / DOCX and offers document-authoring subcommands (`generate`, `fill`, `seal`, `patch`, `redact`, `lint`, `validate`, `render`). All of those are intentionally outside this skill's scope; see "When NOT to use". Conversion-quality flags (`--dedupe-headers`, `--keep-empty-cols`, `--inline-images`) and the `chunks` format are documented in `resources/execution-protocol.md`.
+
+## References
+- Execution protocol: `resources/execution-protocol.md`
+- Troubleshooting: `resources/troubleshooting.md`
+- Configuration: read the `hwp:` section of `.agents/oma-config.yaml` first, then fall back to `config/hwp-config.yaml` for any key it does not set (`supported_formats` lives only in the skill config). User overrides belong in `.agents/oma-config.yaml`, since `oma update` overwrites the skill config.
+- Upstream: https://github.com/chrisryugj/kordoc
+- Related: `../oma-pdf/SKILL.md` (use for `.pdf` inputs)

package/skills/oma-hwp/config/hwp-config.yaml

@@ -0,0 +1,35 @@
+# oma-hwp configuration
+# HWP / HWPX / HWPML to Markdown conversion settings
+#
+# NOT the place to put your settings: `oma update` overwrites this file. Put
+# overrides under `hwp:` in .agents/oma-config.yaml, which is preserved —
+# that section wins, and this file supplies only the shipped defaults the skill
+# falls back to. Migration 022 moves anything you changed here for you.
+#
+
+format: markdown              # "markdown" (default), "json", or "chunks" (RAG structural chunks)
+
+# kordoc version policy
+# - "latest": always use latest (recommended for active kordoc development)
+# - "pinned": use the version in `version.pinned`
+#   (verify with `npm view kordoc version` before pinning; the example below may be stale)
+version:
+  channel: latest
+  pinned: "4.7.3"
+
+# Output behavior
+output:
+  # When no output directory is specified:
+  # "same_dir" = output next to the input file
+  # "cwd" = output in current working directory
+  default_location: same_dir
+
+# Officially supported formats (advertised scope).
+# kordoc supports more formats, but this skill only covers the Korean word
+# processor family. Route other inputs to the appropriate skill:
+# - .pdf  -> oma-pdf
+# - .xlsx / .docx -> out of scope (run `bunx kordoc ...` manually; oma-docs is the doc-drift skill, not a converter)
+supported_formats:
+  - hwp
+  - hwpx
+  - hwpml

package/skills/oma-hwp/resources/balanced-tables.ts

@@ -0,0 +1,39 @@
+/**
+ * Replace balanced outermost table blocks. Nested tables are passed to the
+ * callback as part of their parent instead of being truncated at the first
+ * closing tag.
+ */
+export function replaceBalancedTables(
+  source: string,
+  replace: (tableHtml: string) => string,
+): string {
+  const tag = /<\/?table\b[^>]*>/gi;
+  let depth = 0;
+  let blockStart = -1;
+  let cursor = 0;
+  let output = "";
+
+  for (let match = tag.exec(source); match; match = tag.exec(source)) {
+    const closing = /^<\/table/i.test(match[0]);
+    if (!closing) {
+      if (depth === 0) {
+        blockStart = match.index;
+        output += source.slice(cursor, blockStart);
+      }
+      depth += 1;
+      continue;
+    }
+
+    if (depth === 0) continue;
+    depth -= 1;
+    if (depth === 0 && blockStart >= 0) {
+      const blockEnd = tag.lastIndex;
+      output += replace(source.slice(blockStart, blockEnd));
+      cursor = blockEnd;
+      blockStart = -1;
+    }
+  }
+
+  // Preserve malformed/unclosed input verbatim rather than dropping content.
+  return output + source.slice(blockStart >= 0 ? blockStart : cursor);
+}

package/skills/oma-hwp/resources/execution-protocol.md

@@ -0,0 +1,145 @@
+# HWP Conversion - Execution Protocol
+
+## Step 0: Validate Input
+
+1. Confirm the input file path exists
+2. Check extension is one of `.hwp`, `.hwpx`, `.hwpml`
+   - If `.pdf` -> hand off to `oma-pdf`
+   - If `.xlsx` / `.docx` -> not in scope; advise user to run `bunx kordoc@latest <file>` directly
+3. Check file size (`wc -c` or `ls -lh`); warn if >100MB
+4. Determine output location:
+   - If user specified output path (`-o` or `-d`) → use it
+   - Otherwise → same directory as the input file
+5. Determine output filename: `{input_basename}.md`
+
+## Step 1: Check Runtime
+
+```bash
+bun --version
+```
+
+If `bun` is not available, ask the user to install Bun (https://bun.sh). `bunx` is required.
+
+## Step 2: Convert
+
+> **Important**: Without `-o` or `-d`, kordoc prints the Markdown to **stdout** and does not create a file. Always pass an explicit output path to match this skill's "same directory as input" convention.
+
+### Standard conversion (single file, write next to input)
+```bash
+bunx kordoc@latest "{input_path}" -o "{output_path}"
+# {output_path} = "{dirname(input_path)}/{basename_without_ext(input_path)}.md"
+```
+
+### Output directory (multiple files)
+```bash
+bunx kordoc@latest "{input_pattern}" -d "{output_dir}"
+```
+
+### Print to stdout (piping / preview)
+```bash
+bunx kordoc@latest "{input_path}"
+# No file written; useful when piping to another tool
+```
+
+### Page / section range
+```bash
+bunx kordoc@latest "{input_path}" -p "{range}"
+```
+
+### JSON output (structured intermediate form)
+```bash
+bunx kordoc@latest "{input_path}" --format json
+```
+
+### RAG chunks output (structural chunk JSON)
+```bash
+bunx kordoc@latest "{input_path}" --format chunks
+```
+Emits RAG-oriented structural chunks: each chunk carries a heading / outline-hierarchy breadcrumb, and tables become standalone chunks. Prefer this over plain Markdown when the user is preparing HWP content for RAG ingestion or embedding pipelines.
+
+### Conversion-quality flags (HWP-family relevant)
+| Flag | Effect | When to use |
+|------|--------|-------------|
+| `--dedupe-headers` | Removes running headers repeated per page in HWP5 layout tables (default off) | Paginated forms where the same header row repeats; beware: may over-remove per-attachment renumbering |
+| `--keep-empty-cols` | Preserves trailing empty table columns (form input fields); default trims them | Government form templates where blank fill-in columns are meaningful |
+| `--inline-images` | Inlines images as base64 data URIs (BMP→PNG compression, HWP5 only) | Single self-contained Markdown file needed; skips writing an assets directory for inlined images |
+
+Notes:
+- Default format is `markdown`. Pass `--format json` for the structured AST, `--format chunks` for RAG chunks.
+- `--silent` suppresses progress output, useful in automation / piping contexts.
+
+## Step 2.5: Post-process kordoc output (default)
+
+`resources/flatten-tables.ts` cleans up two kordoc artifacts that hurt downstream use:
+
+1. **HTML `<table>` blocks**: kordoc emits these when a table has `colspan` / `rowspan` because GFM cannot represent merged cells. Converted to GFM pipe tables via `turndown-plugin-gfm`.
+2. **Private Use Area characters**: HWP references Hancom-font-specific glyphs via U+E000-U+F8FF / U+F0000-U+FFFFD / U+100000-U+10FFFD code points. Without the Hancom font these render as blanks or tofu squares. Silently stripped.
+
+```bash
+bun "{skill_resources}/flatten-tables.ts" "{output_path}"
+```
+
+- `{skill_resources}` = this skill's `resources/` directory (`.agents/skills/oma-hwp/resources` in project mode, `~/.agents/skills/oma-hwp/resources` in global mode)
+- Ensure `bun install` has been run once inside that directory (it installs `turndown` + `turndown-plugin-gfm` locally)
+- Merged cells get flattened during the conversion (accepted trade-off)
+- Skip this step only if the caller explicitly needs HTML tables or PUA characters preserved (rare)
+
+## Step 3: Verify
+
+1. Read the generated Markdown file
+2. Verify structure:
+   - Headings preserved (`#`, `##`, etc.)
+   - Tables rendered (GFM pipe syntax, or HTML `<table>` fallback for merged cells)
+   - Lists maintained (bullets, numbered)
+   - Images referenced (relative paths or inline)
+   - Footnotes linked via `[^id]`
+3. If the file is empty or clearly garbled, consult `troubleshooting.md`
+4. If output directory is temporary, move the file to the target location
+5. If the user needs the content in-conversation, read and present it
+
+## Step 4: Report
+
+Tell the user:
+- Output file path
+- Source format detected (HWP5 / HWPX / HWPML)
+- Any issues encountered (encrypted segments, missing tables, best-effort DRM extraction)
+- Page/section count if available
+
+## Error Recovery
+
+| Error | Recovery |
+|-------|----------|
+| `bunx` / `bun` not found | Ask user to install Bun: `curl -fsSL https://bun.sh/install \| bash` |
+| `지원하지 않는 파일 형식` / `unsupported file format` | Confirm extension matches actual content; check magic bytes |
+| `암호화된 문서` / `encrypted document` | Ask user for password; current kordoc CLI may not accept it inline (document as limitation) |
+| Empty Markdown output | Likely a scanned-image-only HWP; suggest OCR pipeline (out of this skill's scope) |
+| Broken / missing tables | Complex merged-cell tables fall back to HTML `<table>`; accept as best-effort |
+| kordoc crash or stack trace | Ensure `@latest` is passed (bunx cache can be stale); if persistent, capture fixture and file issue upstream at https://github.com/chrisryugj/kordoc/issues |
+| Slow conversion on large files | Use `-p` to narrow the page range; process sections separately |
+
+## Pin vs Latest
+
+- **Default**: `bunx kordoc@latest` (always latest). Gets upstream fixes automatically. `@latest` is required because a bare `bunx kordoc` can reuse a stale cached version indefinitely.
+- **Reproducibility**: pin with `bunx kordoc@4.7.3 ...` or similar. Record the pinned version under `hwp.version` in `.agents/oma-config.yaml` (`channel: pinned`, `pinned: "4.7.3"`). Do not edit `config/hwp-config.yaml` — `oma update` overwrites it.
+
+## Scope Reminder
+
+If the user hands you a `.pdf` / `.xlsx` / `.docx` with this skill activated, **do not proceed**. Redirect:
+
+- `.pdf` → switch to `oma-pdf`
+- `.xlsx` / `.docx` → ask the user to run `bunx kordoc@latest <file>` directly; this skill does not advertise those formats
+
+Likewise, document **authoring / editing** requests are out of this skill's scope even though kordoc supports them. Point the user at the subcommand directly:
+
+| Request | kordoc subcommand |
+|---------|-------------------|
+| Generate HWPX from Markdown | `bunx kordoc@latest generate <md> -o <hwpx>` |
+| Fill form blanks | `bunx kordoc@latest fill <template> -f 'k=v,...' -o <out>` |
+| Place stamp/signature image | `bunx kordoc@latest seal <file> --image <png> --anchor "(인)" -o <out>` |
+| Apply edited Markdown back to original | `bunx kordoc@latest patch <original> <edited-md> -o <out>` |
+| Mask personal data (주민번호 etc.) | `bunx kordoc@latest redact <files...>` |
+| Check official-document notation | `bunx kordoc@latest lint <file>` |
+| Validate HWPX structure | `bunx kordoc@latest validate <file>` |
+| Layout-preserving SVG render | `bunx kordoc@latest render <file> -o <svg>` |
+
+kordoc technically supports all of the above, but routing keeps skill scopes clean.

package/skills/oma-hwp/resources/flatten-tables.ts

@@ -0,0 +1,101 @@
+#!/usr/bin/env bun
+/// <reference path="./turndown-plugin-gfm.d.ts" />
+/**
+ * flatten-tables.ts: post-process kordoc output:
+ *   1. convert HTML <table> blocks to GFM pipe tables
+ *   2. strip Private Use Area characters (Hancom font-specific glyphs)
+ *
+ * (1) kordoc emits HTML <table> when a table has colspan/rowspan because GFM
+ *     cannot represent merged cells. This script trades merge-cell fidelity
+ *     for a pure-Markdown output.
+ * (2) HWP references Hancom-font-specific glyphs via Private Use Area code
+ *     points (U+E000-U+F8FF, U+F0000-U+FFFFD, U+100000-U+10FFFD). Without
+ *     the Hancom font these render as blanks or tofu squares; stripping is
+ *     the pragmatic default for AI / plain-MD consumption.
+ *
+ * Usage: bun flatten-tables.ts <file.md> [<file.md>...]
+ */
+
+import { constants } from "node:fs";
+import { access, readFile, writeFile } from "node:fs/promises";
+import TurndownService from "turndown";
+import { tables } from "turndown-plugin-gfm";
+import { replaceBalancedTables } from "./balanced-tables.js";
+
+export { replaceBalancedTables } from "./balanced-tables.js";
+
+const td = new TurndownService({
+  headingStyle: "atx",
+  codeBlockStyle: "fenced",
+  emDelimiter: "*",
+  bulletListMarker: "-",
+});
+td.use(tables);
+
+const files = process.argv.slice(2);
+if (import.meta.main && files.length === 0) {
+  console.error("Usage: bun flatten-tables.ts <file.md> [<file.md>...]");
+  process.exit(1);
+}
+
+const PUA = /[\uE000-\uF8FF\u{F0000}-\u{FFFFD}\u{100000}-\u{10FFFD}]/gu;
+
+async function main(): Promise<void> {
+  for (const path of files) {
+    try {
+      await access(path, constants.F_OK);
+    } catch {
+      console.error(`[flatten-tables] not found: ${path}`);
+      process.exitCode = 1;
+      continue;
+    }
+
+    const src = await readFile(path, "utf8");
+
+    let tableCount = 0;
+    let keptCount = 0;
+    let out = replaceBalancedTables(src, (match: string) => {
+      const nestedTableCount = (match.match(/<table\b/gi) ?? []).length;
+      if (nestedTableCount > 1) {
+        keptCount += 1;
+        return match;
+      }
+      const converted = td.turndown(match).trim();
+      // turndown-plugin-gfm only converts tables whose first row is <th>
+      // (kordoc always emits one); anything else is kept as HTML — do not
+      // count it as flattened.
+      if (converted.startsWith("<table")) {
+        keptCount += 1;
+        return match;
+      }
+      tableCount += 1;
+      return `\n\n${converted}\n\n`;
+    });
+
+    let puaCount = 0;
+    out = out.replace(PUA, () => {
+      puaCount += 1;
+      return "";
+    });
+
+    if (tableCount === 0 && puaCount === 0) {
+      const kept = keptCount ? ` (${keptCount} table(s) kept as HTML: no <th> heading row)` : "";
+      console.log(`[flatten-tables] ${path}: nothing to change${kept}`);
+      continue;
+    }
+
+    await writeFile(path, out, "utf8");
+    const parts: string[] = [];
+    if (tableCount) parts.push(`${tableCount} table(s) flattened`);
+    if (keptCount) parts.push(`${keptCount} table(s) kept as HTML (no <th> heading row)`);
+    if (puaCount) parts.push(`${puaCount} PUA char(s) stripped`);
+    console.log(`[flatten-tables] ${path}: ${parts.join(", ")}`);
+  }
+}
+
+if (import.meta.main) {
+  main().catch((err: unknown) => {
+    console.error("[flatten-tables]", err);
+    process.exit(1);
+  });
+}

package/skills/oma-hwp/resources/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "oma-hwp-postprocess",
+  "private": true,
+  "type": "module",
+  "dependencies": {
+    "turndown": "^7.2.4",
+    "turndown-plugin-gfm": "^1.0.2"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.1",
+    "@types/turndown": "^5.0.6"
+  }
+}