folioqueue 0.1.0__tar.gz

folioqueue-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.coverage*
+htmlcov/
+dist/
+build/
+*.egg-info/
+demo-output/
+demo-input/
+.local/

folioqueue-0.1.0/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## 0.1.0 — 2026-09-08
+
+Initial alpha release.
+
+- Local recursive TXT/Markdown/CSV conversion with optional MarkItDown PDF/DOCX/HTML extraction.
+- Bounded one-file worker processes and timeout/error isolation.
+- Input snapshots, checksum-based incremental decisions and per-file write-ahead checkpoints.
+- Conservative output ownership and source-extension-preserving names.
+- Read-only plan command, JSON/HTML reports and stable exit codes.
+- Synthetic regression fixtures, cross-platform CI and English/Chinese documentation.
+
+Known limits: no OCR, no packaged desktop app, no hostile-document sandbox. See the README and validation record.

folioqueue-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,32 @@
+# Contributing
+
+FolioQueue welcomes reproducible bug reports, documentation corrections, compatibility tests and focused changes to the local conversion workflow.
+
+## Before contributing
+
+Read the README and `docs/design.md`. Discuss large features before implementation; the initial scope intentionally excludes OCR, cloud services, desktop UI, RAG chunking and an HTTP API.
+
+For a bug report, include your OS, Python and FolioQueue/MarkItDown versions, command flags, expected behavior and the report's error code. Attach only synthetic or non-sensitive samples you are authorized to share. Filenames and reports can be sensitive. Do not attach your private ledger or real customer documents.
+
+## Development checks
+
+```bash
+python -m pip install -e ".[test,documents]"
+python -m pytest --cov=folioqueue --cov-report=term-missing
+python -m ruff check .
+python -m ruff format --check .
+python -m build
+python -m twine check dist/*
+```
+
+Tests should demonstrate an observable contract or failure recovery, not repeat the implementation. Parser fixes need a small redistributable fixture. Please identify which platforms you actually tested.
+
+Keep changes focused, describe the problem and final behavior, and include validation. Preserve existing output-ownership guarantees. Contributions are accepted under the repository's MIT license; preserve third-party notices when appropriate.
+
+## AI-assisted contributions
+
+AI assistance is welcome. The contributor is responsible for understanding the change, verifying behavior and checking attribution.
+
+## Maintenance
+
+The repository owner, GokouRuri43, is the initial maintainer. Release review covers tests, package install smoke checks, documentation accuracy and known limitations. No response-time SLA is offered.

folioqueue-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GokouRuri43
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

folioqueue-0.1.0/PKG-INFO

@@ -0,0 +1,171 @@
+Metadata-Version: 2.4
+Name: folioqueue
+Version: 0.1.0
+Summary: Restartable local document-to-Markdown batches with a checksum ledger and failure isolation
+Project-URL: Homepage, https://github.com/GokouRuri43/folioqueue
+Project-URL: Issues, https://github.com/GokouRuri43/folioqueue/issues
+Project-URL: Changelog, https://github.com/GokouRuri43/folioqueue/blob/main/CHANGELOG.md
+Author: GokouRuri43
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,document-conversion,incremental,markdown,markitdown
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Requires-Python: >=3.11
+Provides-Extra: documents
+Requires-Dist: markitdown[docx,pdf]<0.2,>=0.1.7; extra == 'documents'
+Provides-Extra: test
+Requires-Dist: build<2,>=1; extra == 'test'
+Requires-Dist: pytest-cov<8,>=6; extra == 'test'
+Requires-Dist: pytest<10,>=8; extra == 'test'
+Requires-Dist: ruff<1,>=0.11; extra == 'test'
+Requires-Dist: twine<7,>=6; extra == 'test'
+Description-Content-Type: text/markdown
+
+# FolioQueue
+
+**Restartable local document-to-Markdown batches, with a checksum ledger and inspectable failures.**
+
+[![CI](https://github.com/GokouRuri43/folioqueue/actions/workflows/ci.yml/badge.svg)](https://github.com/GokouRuri43/folioqueue/actions/workflows/ci.yml)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+[简体中文](README.zh-CN.md) · [Design](docs/design.md) · [Validation](docs/validation.md) · [Contributing](CONTRIBUTING.md)
+
+FolioQueue helps maintain a Markdown copy of a **local document collection**. It snapshots each input, converts files in separate processes, checkpoints completed work, and checks both source and output hashes before skipping an unchanged file. A broken document can fail while the rest of the batch finishes.
+
+**Status: 0.1.0 alpha.** See the validation record for what has actually been tested.
+
+## Who is this for?
+
+- **Note / knowledge-base maintainers** folding PDFs, Word and HTML into a Markdown vault, and keeping it in sync as sources change.
+- **Local RAG / LLM corpus builders** who need a reproducible, incremental Markdown mirror of a document folder to index.
+- **Self-hosted archive keepers** who want failures isolated per file and edited output protected, instead of a one-shot bulk convert.
+
+## Why use it?
+
+- **Resume by rerunning.** Completed files are checkpointed individually; failed files are retried on the next run.
+- **Detect real changes.** SHA-256 checksums, rather than timestamps alone, determine whether to convert. Converter dependency changes invalidate document caches.
+- **Protect edits.** Untracked or manually changed output is a conflict, even with `--force`.
+- **Keep names distinct.** `report.pdf` → `documents/report.pdf.md`; `report.docx` → `documents/report.docx.md`.
+- **Contain ordinary failures.** Bounded parallel file processes, per-file timeouts, input/output size checks, and a DOCX expansion preflight.
+- **Inspect every outcome.** Local HTML and JSON reports list converted, skipped, failed, ignored and stale files. Reports omit extracted text and raw converter exceptions.
+- **Plan first.** `plan` shows per-file decisions without creating files.
+
+This is an independently implemented workflow layer. PDF/DOCX/HTML extraction is delegated to [Microsoft MarkItDown](https://github.com/microsoft/markitdown); this project is not affiliated with Microsoft or OpenAI. It does not claim to improve PDF extraction fidelity. [Alternatives and research](docs/research.md).
+
+## Install
+
+Python 3.11 or later is required. Use a virtual environment. On Windows, the Python launcher may be `py` instead of `python`.
+
+```bash
+git clone https://github.com/GokouRuri43/folioqueue.git
+cd folioqueue
+python -m pip install ".[documents]"
+```
+
+`python -m pip install .` installs the dependency-free TXT/Markdown/CSV core. The `documents` extra adds PDF, DOCX and HTML through MarkItDown. A wheel and source archive are also provided in GitHub Releases; the project is **not currently published to PyPI**.
+
+## Try it on the included examples
+
+Run these commands from the repository directory:
+
+```bash
+folioqueue plan examples/documents -o demo-output --json
+folioqueue convert examples/documents -o demo-output
+folioqueue convert examples/documents -o demo-output
+```
+
+The first conversion produces three Markdown files and ignores one unsupported fixture. The second skips all three unchanged files. Open `demo-output/report.html` to inspect the latest run.
+
+For your own collection:
+
+```bash
+folioqueue convert ./documents -o ./markdown-output --workers 2 --timeout 60
+```
+
+On Windows:
+
+```powershell
+folioqueue convert 'C:\My Documents' -o 'C:\Markdown Output' --workers 2
+```
+
+Source and output directories must not overlap. Hidden-name files/directories, symlinks and Windows junctions are skipped. No URL inputs, cloud services, LLM API calls, third-party MarkItDown plugins, or shell commands are used by the conversion workflow. Dependencies must be installed beforehand.
+
+## Supported formats
+
+| Input | Backend | Boundaries |
+| --- | --- | --- |
+| `.txt`, `.md` | Standard library | Strict UTF-8 with optional BOM by default; `--encoding` selects another encoding |
+| `.csv` | Standard library | Comma-separated, first row as header; quoted commas/newlines supported; Markdown cell escaping |
+| `.html`, `.htm` | MarkItDown | Text extraction; no browser, script execution or asset downloading is requested |
+| `.docx` | MarkItDown | Extraction quality follows upstream; no visual layout preservation |
+| `.pdf` | MarkItDown | Text-based PDFs; no OCR, no guarantee of correct reading order or tables |
+
+Empty extracted text is a failure, including a scanned PDF with no text layer. Legacy `.doc`, spreadsheets, slides, images, media, archives and encrypted documents are outside the v0.1 support scope. Source documents remain the authoritative copy.
+
+## Controls and exit codes
+
+```bash
+folioqueue convert ./documents -o ./markdown-output --types txt,csv,docx
+folioqueue convert ./documents -o ./markdown-output --encoding gb18030
+folioqueue convert ./documents -o ./markdown-output --max-input-mb 64 --max-output-mb 32
+folioqueue convert ./documents -o ./markdown-output --force --json
+```
+
+`--workers` is 1–16 (default 2). `--timeout` covers each converter subprocess, including imports, but not scanning, hashing, copying or committing. `--force` reconverts owned, unedited output; it never authorizes overwriting a conflict. Move conflicting output aside or use a new output directory.
+
+| Exit | Meaning |
+| --- | --- |
+| `0` | No failed files / no blocking plan decisions; ignored and stale entries are informational |
+| `1` | At least one failed conversion or planned conflict/error |
+| `2` | Invalid arguments, invalid ledger, overlapping roots, lock contention or a run-level filesystem error |
+| `130` | Interrupted; rerun to continue from completed checkpoints |
+
+Deleted source files are reported as **stale**; their output is retained. A failed updated source can leave the previous Markdown in place. Consumers must check `report.json` and must not assume every existing Markdown file is current. The report describes the most recent completed run, not a global corpus validity certificate.
+
+## Output
+
+```text
+markdown-output/
+  documents/
+    report.pdf.md
+    subfolder/notes.txt.md
+  report.html
+  report.json
+  .folioqueue/
+    state.json
+    writer.lock
+    work/
+```
+
+The private ledger binds an output directory to one absolute source path. Do not edit it or share it as a public artifact. Moving the source requires a new output directory in v0.1. A kernel-managed exclusive writer lock is automatically released on process exit; the lock file may remain and should not be deleted while a run is active.
+
+Interrupted conversions may leave temporary source snapshots in `.folioqueue/work`. Once no run is active, you may remove that directory to reclaim space. A subprocess is **failure isolation, not a security sandbox**; process only trusted documents or use an external sandbox for untrusted inputs. See [SECURITY.md](SECURITY.md).
+
+## Development
+
+```bash
+python -m pip install -e ".[test,documents]"
+python -m pytest --cov=folioqueue --cov-report=term-missing
+python -m ruff check .
+python -m ruff format --check .
+python -m build
+python -m twine check dist/*
+```
+
+The test suite includes synthetic, redistributable PDF/DOCX/HTML fixtures and actual subprocess conversions. CI tests Windows, Linux and macOS. The workflow result, rather than this sentence, is the authority for current pass/fail status.
+
+## Roadmap
+
+1. Collect reproducible reports from document-collection maintainers and improve format diagnostics.
+2. Publish larger, redistributable corpus results and measure overhead, failure behavior and memory use.
+3. Consider an explicit stale-output review command and portable ledger migration after the core behavior is exercised.
+
+Requests for unsupported features belong in issues with a concrete workflow and a minimal non-sensitive sample. No telemetry is collected by FolioQueue.

folioqueue-0.1.0/README.md

@@ -0,0 +1,141 @@
+# FolioQueue
+
+**Restartable local document-to-Markdown batches, with a checksum ledger and inspectable failures.**
+
+[![CI](https://github.com/GokouRuri43/folioqueue/actions/workflows/ci.yml/badge.svg)](https://github.com/GokouRuri43/folioqueue/actions/workflows/ci.yml)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+[简体中文](README.zh-CN.md) · [Design](docs/design.md) · [Validation](docs/validation.md) · [Contributing](CONTRIBUTING.md)
+
+FolioQueue helps maintain a Markdown copy of a **local document collection**. It snapshots each input, converts files in separate processes, checkpoints completed work, and checks both source and output hashes before skipping an unchanged file. A broken document can fail while the rest of the batch finishes.
+
+**Status: 0.1.0 alpha.** See the validation record for what has actually been tested.
+
+## Who is this for?
+
+- **Note / knowledge-base maintainers** folding PDFs, Word and HTML into a Markdown vault, and keeping it in sync as sources change.
+- **Local RAG / LLM corpus builders** who need a reproducible, incremental Markdown mirror of a document folder to index.
+- **Self-hosted archive keepers** who want failures isolated per file and edited output protected, instead of a one-shot bulk convert.
+
+## Why use it?
+
+- **Resume by rerunning.** Completed files are checkpointed individually; failed files are retried on the next run.
+- **Detect real changes.** SHA-256 checksums, rather than timestamps alone, determine whether to convert. Converter dependency changes invalidate document caches.
+- **Protect edits.** Untracked or manually changed output is a conflict, even with `--force`.
+- **Keep names distinct.** `report.pdf` → `documents/report.pdf.md`; `report.docx` → `documents/report.docx.md`.
+- **Contain ordinary failures.** Bounded parallel file processes, per-file timeouts, input/output size checks, and a DOCX expansion preflight.
+- **Inspect every outcome.** Local HTML and JSON reports list converted, skipped, failed, ignored and stale files. Reports omit extracted text and raw converter exceptions.
+- **Plan first.** `plan` shows per-file decisions without creating files.
+
+This is an independently implemented workflow layer. PDF/DOCX/HTML extraction is delegated to [Microsoft MarkItDown](https://github.com/microsoft/markitdown); this project is not affiliated with Microsoft or OpenAI. It does not claim to improve PDF extraction fidelity. [Alternatives and research](docs/research.md).
+
+## Install
+
+Python 3.11 or later is required. Use a virtual environment. On Windows, the Python launcher may be `py` instead of `python`.
+
+```bash
+git clone https://github.com/GokouRuri43/folioqueue.git
+cd folioqueue
+python -m pip install ".[documents]"
+```
+
+`python -m pip install .` installs the dependency-free TXT/Markdown/CSV core. The `documents` extra adds PDF, DOCX and HTML through MarkItDown. A wheel and source archive are also provided in GitHub Releases; the project is **not currently published to PyPI**.
+
+## Try it on the included examples
+
+Run these commands from the repository directory:
+
+```bash
+folioqueue plan examples/documents -o demo-output --json
+folioqueue convert examples/documents -o demo-output
+folioqueue convert examples/documents -o demo-output
+```
+
+The first conversion produces three Markdown files and ignores one unsupported fixture. The second skips all three unchanged files. Open `demo-output/report.html` to inspect the latest run.
+
+For your own collection:
+
+```bash
+folioqueue convert ./documents -o ./markdown-output --workers 2 --timeout 60
+```
+
+On Windows:
+
+```powershell
+folioqueue convert 'C:\My Documents' -o 'C:\Markdown Output' --workers 2
+```
+
+Source and output directories must not overlap. Hidden-name files/directories, symlinks and Windows junctions are skipped. No URL inputs, cloud services, LLM API calls, third-party MarkItDown plugins, or shell commands are used by the conversion workflow. Dependencies must be installed beforehand.
+
+## Supported formats
+
+| Input | Backend | Boundaries |
+| --- | --- | --- |
+| `.txt`, `.md` | Standard library | Strict UTF-8 with optional BOM by default; `--encoding` selects another encoding |
+| `.csv` | Standard library | Comma-separated, first row as header; quoted commas/newlines supported; Markdown cell escaping |
+| `.html`, `.htm` | MarkItDown | Text extraction; no browser, script execution or asset downloading is requested |
+| `.docx` | MarkItDown | Extraction quality follows upstream; no visual layout preservation |
+| `.pdf` | MarkItDown | Text-based PDFs; no OCR, no guarantee of correct reading order or tables |
+
+Empty extracted text is a failure, including a scanned PDF with no text layer. Legacy `.doc`, spreadsheets, slides, images, media, archives and encrypted documents are outside the v0.1 support scope. Source documents remain the authoritative copy.
+
+## Controls and exit codes
+
+```bash
+folioqueue convert ./documents -o ./markdown-output --types txt,csv,docx
+folioqueue convert ./documents -o ./markdown-output --encoding gb18030
+folioqueue convert ./documents -o ./markdown-output --max-input-mb 64 --max-output-mb 32
+folioqueue convert ./documents -o ./markdown-output --force --json
+```
+
+`--workers` is 1–16 (default 2). `--timeout` covers each converter subprocess, including imports, but not scanning, hashing, copying or committing. `--force` reconverts owned, unedited output; it never authorizes overwriting a conflict. Move conflicting output aside or use a new output directory.
+
+| Exit | Meaning |
+| --- | --- |
+| `0` | No failed files / no blocking plan decisions; ignored and stale entries are informational |
+| `1` | At least one failed conversion or planned conflict/error |
+| `2` | Invalid arguments, invalid ledger, overlapping roots, lock contention or a run-level filesystem error |
+| `130` | Interrupted; rerun to continue from completed checkpoints |
+
+Deleted source files are reported as **stale**; their output is retained. A failed updated source can leave the previous Markdown in place. Consumers must check `report.json` and must not assume every existing Markdown file is current. The report describes the most recent completed run, not a global corpus validity certificate.
+
+## Output
+
+```text
+markdown-output/
+  documents/
+    report.pdf.md
+    subfolder/notes.txt.md
+  report.html
+  report.json
+  .folioqueue/
+    state.json
+    writer.lock
+    work/
+```
+
+The private ledger binds an output directory to one absolute source path. Do not edit it or share it as a public artifact. Moving the source requires a new output directory in v0.1. A kernel-managed exclusive writer lock is automatically released on process exit; the lock file may remain and should not be deleted while a run is active.
+
+Interrupted conversions may leave temporary source snapshots in `.folioqueue/work`. Once no run is active, you may remove that directory to reclaim space. A subprocess is **failure isolation, not a security sandbox**; process only trusted documents or use an external sandbox for untrusted inputs. See [SECURITY.md](SECURITY.md).
+
+## Development
+
+```bash
+python -m pip install -e ".[test,documents]"
+python -m pytest --cov=folioqueue --cov-report=term-missing
+python -m ruff check .
+python -m ruff format --check .
+python -m build
+python -m twine check dist/*
+```
+
+The test suite includes synthetic, redistributable PDF/DOCX/HTML fixtures and actual subprocess conversions. CI tests Windows, Linux and macOS. The workflow result, rather than this sentence, is the authority for current pass/fail status.
+
+## Roadmap
+
+1. Collect reproducible reports from document-collection maintainers and improve format diagnostics.
+2. Publish larger, redistributable corpus results and measure overhead, failure behavior and memory use.
+3. Consider an explicit stale-output review command and portable ledger migration after the core behavior is exercised.
+
+Requests for unsupported features belong in issues with a concrete workflow and a minimal non-sensitive sample. No telemetry is collected by FolioQueue.

folioqueue-0.1.0/README.zh-CN.md

@@ -0,0 +1,70 @@
+# FolioQueue
+
+**可重复执行、逐文件保存进度的本地文档转 Markdown 工具。**
+
+[English](README.md) · [设计](docs/design.md) · [验证记录](docs/validation.md)
+
+适合维护本地文档集合和知识库：文件变化后重新转换，未变化的文件跳过，失败文件下次重试。PDF、DOCX、HTML 的底层提取使用 Microsoft MarkItDown；TXT、Markdown、CSV 使用 Python 标准库。
+
+**当前为 0.1.0 alpha。** 它是独立的工作流工具，与 Microsoft、OpenAI 没有隶属关系。
+
+## 适用人群
+
+- **笔记 / 知识库维护者**：把 PDF、Word、HTML 并入 Markdown 库，并在源文件变化后保持同步。
+- **本地 RAG / LLM 语料构建者**：需要一个可复现、增量的 Markdown 镜像目录用于索引。
+- **自托管资料整理者**：希望失败按文件隔离、已编辑输出不被覆盖，而不是一次性批量转换。
+
+## 安装和使用
+
+需要 Python 3.11 或以上，建议在虚拟环境安装。Windows 的 Python 命令可能是 `py`。
+
+```bash
+git clone https://github.com/GokouRuri43/folioqueue.git
+cd folioqueue
+python -m pip install ".[documents]"
+folioqueue plan examples/documents -o demo-output --json
+folioqueue convert examples/documents -o demo-output
+folioqueue convert examples/documents -o demo-output
+```
+
+第一次转换三个示例文件并忽略一个不支持的文件；第二次应跳过三个未变化文件。打开 `demo-output/report.html` 查看结果。
+
+仅需要 TXT、Markdown、CSV 时，执行 `python -m pip install .`，核心没有第三方运行依赖。GitHub Releases 提供 wheel 和源码包；**目前没有发布到 PyPI**。
+
+转换自己的文件夹：
+
+```powershell
+folioqueue convert 'C:\My Documents' -o 'C:\Markdown Output' --workers 2 --timeout 60
+```
+
+输入和输出目录必须互不包含。默认递归扫描，跳过以点开头的文件/目录、符号链接和 Windows junction。支持 `.txt .md .csv .html .htm .docx .pdf`，不支持 OCR、旧版 `.doc`、表格文件、演示文稿、音视频、压缩包或 URL。
+
+## 行为约定
+
+- 每个文件在独立进程中转换，有超时与大小检查；一个文件失败不会让其他文件一起失败。
+- 每完成一个文件保存一次检查点；中断后重新运行原命令即可继续。
+- SHA-256 同时检查源文件和输出；修改时间不变也能检测到内容变化。
+- 手动修改的输出或工具未记录的同名文件会报冲突，`--force` 也不会覆盖。请将冲突文件另存，或使用新输出目录。
+- 保留原扩展名，例如 `报告.pdf` 输出为 `documents/报告.pdf.md`，避免与 `报告.docx` 冲突。
+- 源文件被删除后，旧输出会保留并标记为 stale；更新失败也可能保留上次成功结果。导入知识库前需要检查报告。
+- 报告包含相对文件名和状态，不包含提取正文或转换库的原始异常。文件名仍可能敏感。
+- 转换流程不配置云服务或 LLM，不启用 MarkItDown 第三方插件。依赖需要预先安装。
+
+## 常用选项
+
+```bash
+folioqueue convert ./documents -o ./out --types txt,csv,docx
+folioqueue convert ./documents -o ./out --encoding gb18030
+folioqueue convert ./documents -o ./out --max-input-mb 64 --max-output-mb 32
+folioqueue convert ./documents -o ./out --force --json
+```
+
+并发默认 2，范围 1–16；转换子进程默认超时 60 秒。超时不包含扫描、校验和计算、复制和写入。CSV 为逗号分隔，第一行作为表头；文本默认严格按 UTF-8（兼容 BOM）解码。
+
+退出码：`0` 无失败，`1` 有文件失败/计划冲突，`2` 参数或运行环境错误，`130` 被中断。`report.html` 和 `report.json` 是最近一次完成的运行报告，不代表目录中每个 Markdown 都一定是最新内容。
+
+`.folioqueue/state.json` 包含绝对源目录和校验记录，不应手动修改或公开分享。源目录迁移时请使用新输出目录。强制终止后可能在 `.folioqueue/work` 留下源文件快照，确认没有运行中的任务后可手动删除该目录。
+
+独立进程用于隔离普通故障，**不是安全沙箱**。处理不可信文件需要额外沙箱；大小检查也不是操作系统级内存限制。详见 [安全边界](SECURITY.md)。
+
+欢迎提交可复现问题和脱敏样例。

folioqueue-0.1.0/SECURITY.md

@@ -0,0 +1,24 @@
+# Security policy and boundaries
+
+The 0.1.x release line receives fixes as maintainers are able. This alpha has not undergone an independent security audit.
+
+## Reporting
+
+If private vulnerability reporting is enabled, use the repository's **Security → Report a vulnerability** flow. If unavailable, open a minimal issue requesting a private contact channel without posting exploit details, documents, tokens or private filesystem paths.
+
+## Threat model
+
+FolioQueue is for trusted local documents in a directory controlled by the user. It does not configure LLM/cloud clients, enable third-party MarkItDown plugins, call a shell or accept URL inputs. Optional parsers and their transitive dependencies are still part of the trusted computing base. Ordinary process isolation is not a security sandbox or a network firewall.
+
+Input/output checksums, a cooperative writer lock, path checks, input snapshots, atomic output replacement, timeouts and admission limits reduce common operational failures. They do not protect against a compromised parser, malicious local process, filesystem race, resource exhaustion inside a parser, or a deliberately modified ledger.
+
+The worker runs with the user's account permissions. Run untrusted documents only inside a separate sandbox with OS-enforced filesystem, network, CPU and memory limits. Markdown output can contain untrusted links or raw markup; review it before rendering in another application.
+
+## Data retained locally
+
+- Converted Markdown contains document text.
+- The private ledger contains the absolute input root, relative paths and hashes.
+- Reports contain relative filenames and error codes, but omit body text and raw parser exceptions.
+- Temporary snapshots are normally removed after each job. Forced termination may leave copies in `.folioqueue/work`; remove that directory only after confirming no run is active.
+
+Do not publish your output directory without reviewing it. The project itself has no telemetry or analytics code.

folioqueue-0.1.0/docs/design.md

@@ -0,0 +1,47 @@
+# Design and invariants
+
+## Scope
+
+FolioQueue is a workflow layer for repeated conversion of trusted local document collections. It implements scheduling, input snapshots, output ownership, incremental decisions and run reporting. MarkItDown performs the optional document extraction. There is no new PDF parser, OCR engine, browser service, LLM call, or public HTTP endpoint.
+
+## Data flow
+
+1. Validate separate roots and reject symlink/junction path components.
+2. Acquire an OS-managed exclusive lock in the output directory.
+3. Load a schema-versioned ledger bound to the source root; scan selected extensions.
+4. Hash sources and check existing output ownership. A checksum mismatch is a conflict, including under `--force`.
+5. Schedule at most `workers` jobs. Copy each input into a temporary snapshot, checking size and the planned checksum.
+6. Spawn the same Python interpreter as a one-file worker. Discard converter stdout/stderr; accept a small structured status file and bounded Markdown output.
+7. Recheck the live source and output, checkpoint pending ownership, atomically replace Markdown, and checkpoint success.
+8. Write JSON and inert HTML reports for the completed run.
+
+The report is relative-path-only. The private ledger contains an absolute source root to prevent accidental output reuse with an unrelated collection.
+
+## Cache key
+
+TXT/MD/CSV use the FolioQueue version, Python major/minor version and selected text encoding. Document formats additionally include the installed distribution names and versions, so a transitive converter dependency update invalidates document cache entries. This is deliberately conservative: installing an unrelated distribution can also cause reconversion.
+
+Source and output SHA-256 hashes must both match. No timestamp-only fast path is used. Failed conversions are not cached as successful. Missing output is regenerated. `--force` bypasses only the unchanged-file shortcut.
+
+## Commit interruption cases
+
+| Interruption point | Next run |
+| --- | --- |
+| Before pending checkpoint | Previous ledger/output remain authoritative |
+| After pending checkpoint, before output replacement | Old owned hash is accepted, and the file is reconverted |
+| After output replacement, before success checkpoint | Matching new output can be reused if source and fingerprint still match |
+| After success checkpoint | Normal incremental skip |
+
+Atomic replacement is per file. The whole batch is not a transaction, and the two report files are not a transactional pair. A forced stop can leave the previous completed report and temporary snapshots. Always inspect the command exit code. Power-loss durability depends on the filesystem; `fsync` of file contents is used, but this is not a database-grade power-failure guarantee.
+
+## Output ownership
+
+Only checksummed output tracked by the ledger is replaced. Names retain source extensions. Source names that collide under NFC normalization and case folding are rejected before conversion for portability. Output file/directory conflicts (for example, a source `a.txt` next to an `a.txt.md/` directory) are also rejected before conversion. Reports and the private metadata directory are reserved generated paths. Stale outputs are retained, never automatically deleted.
+
+The output directory is an application-managed workspace; do not edit reports or the ledger. Source documents and handwritten Markdown should live elsewhere. An output file edited concurrently after the final ownership check is outside the cooperative-writer model; do not edit output during an active run.
+
+## Resource and security limits
+
+At most 16 worker processes can be requested (default 2). Defaults are 64 MiB input, 32 MiB output and 60 seconds per worker. DOCX archives are limited to 10,000 entries and 256 MiB declared uncompressed data. These are admission/output checks, not OS memory or disk quotas: an underlying parser can allocate substantial memory before returning output. Use an external sandbox and resource limits for hostile documents.
+
+Time limits cover worker startup/imports and conversion. Scanning, hashing, snapshotting and commit I/O are not timed. Only direct child processes are managed; the supported conversion paths do not intentionally launch grandchildren. No protection against a compromised parser, hostile local process, filesystem race, or maliciously edited ledger is claimed.

folioqueue-0.1.0/docs/evidence/synthetic-batch.json

@@ -0,0 +1,48 @@
+{
+  "executed_at": "2026-09-08T06:39:31.915120+00:00",
+  "platform": "Windows",
+  "python": "3.12.14",
+  "folioqueue": "0.1.0",
+  "markitdown": "0.1.7",
+  "workers": 2,
+  "corpus": {
+    "txt": 40,
+    "csv": 10,
+    "docx": 2,
+    "pdf": 2,
+    "html": 2
+  },
+  "runs": [
+    {
+      "scenario": "initial",
+      "summary": {
+        "converted": 56
+      },
+      "duration_seconds": 4.031
+    },
+    {
+      "scenario": "unchanged",
+      "summary": {
+        "skipped": 56
+      },
+      "duration_seconds": 0.219
+    },
+    {
+      "scenario": "one_source_changed",
+      "summary": {
+        "converted": 1,
+        "skipped": 55
+      },
+      "duration_seconds": 0.25
+    },
+    {
+      "scenario": "one_output_edited",
+      "summary": {
+        "failed": 1,
+        "skipped": 55
+      },
+      "duration_seconds": 0.203
+    }
+  ],
+  "limitations": "Small synthetic smoke corpus; not an extraction-quality or comparative throughput benchmark."
+}

folioqueue-0.1.0/docs/research.md

@@ -0,0 +1,26 @@
+# Selection research — 2026-09-08
+
+The following are public demand signals, not customer endorsements and not independently reproduced upstream bug findings.
+
+## Upstream signals
+
+- [MarkItDown #1371](https://github.com/microsoft/markitdown/issues/1371), “Feature Request: Add batch processing capability for directory conversion”: an open request to convert all supported files in a directory (recursively) in one operation, e.g. `markitdown --batch ./documents --output ./converted`. This is the direct scope FolioQueue implements, plus incremental and ownership behavior.
+- [MarkItDown #1166](https://github.com/microsoft/markitdown/issues/1166), “Process multiple files”: an open request to batch-convert a list of files in one invocation. FolioQueue covers this through recursive collection scanning rather than a repeated flag list.
+- [MarkItDown #135](https://github.com/microsoft/markitdown/issues/135), “Support for Parallel Processing of files”: a request and discussion around document-processing throughput. Some comments make unsupported general claims about Python parallelism; FolioQueue does not adopt those claims. A bounded one-file process model is used for failure isolation and scheduling.
+- [MarkItDown #1234](https://github.com/microsoft/markitdown/issues/1234), “Magika Dependency Optional”: a browser/Pyodide use case affected by ONNX dependencies. FolioQueue does **not** solve that upstream browser issue; it keeps its own text/CSV core dependency-free and makes the complete document backend optional.
+- The upstream single-file CLI was inspected at commit [`b6e8bbdce628d564c6af031b5f26cda6e818ea10`](https://github.com/microsoft/markitdown/tree/b6e8bbdce628d564c6af031b5f26cda6e818ea10). FolioQueue implements a separate collection workflow using the published Python package, without copying upstream implementation code.
+
+## Related projects inspected
+
+- [MarkItDown Plus](https://github.com/lamguo/markitdown-plus): folder conversion, workers, manifests, assets, RAG chunking and JSONL. Stronger choice when chunking and assets are central. Its README was reviewed; no claim is made that it lacks an unmentioned capability.
+- [kuma90/markitdown-batch](https://github.com/kuma90/markitdown-batch): Windows GUI/CLI for folder conversion through a LAN API.
+- [shubhankarreddy/markitdown-gui](https://github.com/shubhankarreddy/markitdown-gui): Windows desktop conversion workflow, discovered through repository metadata.
+
+FolioQueue's v0.1 contract focuses on checksum-based resume, conservative output ownership, write-ahead recovery, per-file timeout isolation and read-only planning. These are concrete, testable behaviors.
+
+## Next steps
+
+- Gather external usage on representative, non-sensitive collections.
+- Identify workflows where checkpointing and output-conflict detection materially help.
+- Measure overhead against a simple sequential MarkItDown loop using the same corpus, backend version and hardware.
+- Turn real failure reports into minimal fixtures and fixes.