Document Conversion

Document conversion

Language: English · 简体中文

LWC can adapt Microsoft MarkItDown or Firecrawl Anydoc into a controlled local conversion step. It turns one authorized non-Markdown file into a new reviewable UTF-8 Markdown file.

Conversion is optional, disabled by default, and separate from ingestion. A converted file does not enter Wiki memory until you explicitly add and integrate it as a Source.

When to use it

Use conversion when a task needs reviewable Markdown from a local PDF, Office document, EPUB, or another format supported by the selected adapter.

Skip it when:

• the input is already Markdown or plain text;
• the source can be reviewed safely without a derived file;
• ordinary recall already answers the task;
• the adapter cannot preserve information needed for the decision.

Format support belongs to the selected adapter and its installed extras. LWC does not claim that every format has lossless conversion.

Choose one optional adapter

Inspect effective configuration first:

lwc --scope project config show

Install and select exactly one adapter only after explaining local file access and receiving consent.

Firecrawl Anydoc:

npm install --global @firecrawl/anydoc
lwc --scope project config set --trans anydoc

Microsoft MarkItDown with all optional format extras:

python3 -m pip install 'markitdown[all]'
lwc --scope project config set --trans markitdown

LWC never installs either adapter, silently switches engines, or falls back from one engine to the other. The selected executable must be available on PATH.

Timeout and adapter arguments

The default timeout is 120 seconds and the accepted range is 1–900 seconds. Configuration can replace the selected engine's argument list:

lwc --scope project config set \
  --trans markitdown \
  --trans-timeout 300 \
  --trans-arg --keep-data-uris

LWC applies an engine-specific allowlist again at execution time. Extra positional inputs, output flags, -- injection, and unsupported options are rejected. This prevents configuration from replacing LWC's input or output paths.

Credentials never belong in --trans-arg, config files, logs, or generated Markdown. If an adapter feature requires credentials, provide them through that adapter's documented environment mechanism and keep them outside durable output.

Convert one file

lwc --scope project trans docs/report.docx --output converted/report.md

The input must be an existing regular file no larger than 64 MiB. In project scope, a path outside the active project root requires explicit acknowledgement for that invocation:

lwc --scope project trans ../shared/report.pdf \
  --output converted/report.md \
  --allow-external-source

Use that flag only after confirming the exact external file belongs in the current authorized task. Symlink resolution cannot be used to bypass the project boundary.

Safe output publication

The output path must:

• name a new file;
• differ from the input;
• have an available real parent directory;
• remain no larger than 64 MiB;
• contain non-empty valid UTF-8.

LWC writes adapter output to private temporary files, applies the configured timeout to the process tree, validates the result, and publishes with create-new semantics. It never overwrites an existing destination. A concurrent output creation is reported instead of replaced.

The receipt reports:

• selected engine;
• canonical input path;
• output path;
• output byte count;
• SHA-256 output digest.

The receipt proves which bytes were published. It does not prove conversion completeness or source ingestion.

Review before ingestion

Inspect the complete Markdown for:

• missing pages, sheets, slides, images, tables, or footnotes;
• damaged heading hierarchy or reading order;
• OCR errors and lost characters;
• accidental credentials or private data;
• adapter warnings that change meaning.

Only then, if the derived document belongs in persistent memory, start the normal and separate ingestion workflow:

lwc source add converted/report.md

That command creates its own immutable Source receipt, ingest job, citations, and review obligations. Conversion alone creates none of them and does not write an LWC operation-log entry.

Agent readiness

Lifecycle readiness reports:

• the effective md_trans setting and origin;
• adapters detected on PATH;
• whether the selected executable is available;
• the configuration command for each supported adapter.

Hooks may explain a missing or unselected adapter only when conversion is relevant. They must never install or enable one automatically.

Completion evidence

Conversion is complete when:

• configuration identifies one selected adapter, timeout, and reviewed arguments;
• the exact input path was authorized;
• a new in-scope UTF-8 Markdown file was published without overwrite;
• byte count and SHA-256 receipt match the output;
• the full Markdown was reviewed for completeness and sensitive data;
• any requested ingestion has its own Source and citation lifecycle.

Next: MCP server and lwc_explore