Metadata-Version: 2.4
Name: mmdoc
Version: 0.1.1
Summary: A folder-based multimodal document format and CLI for AI-native research
Project-URL: Homepage, https://github.com/hsurick/mmdoc
Project-URL: Repository, https://github.com/hsurick/mmdoc
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: ai-agents,clipboard,documents,docx,google-docs,images,markdown,multimodal,pandoc
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Text Processing :: Markup :: Markdown
Requires-Python: >=3.11
Requires-Dist: pyyaml>=6
Requires-Dist: typer>=0.12
Description-Content-Type: text/markdown

# mmdoc

**A folder-based multimodal document format so AI agents can search, read, and edit
image-bearing docs with ordinary file tools.**

## The problem

Research is text + tables + images, but Markdown can only *reference* images, not hold
them — and AI agents are now the primary readers. Content trapped in a screenshot is
invisible to `grep`; an agent can't see a referenced image without extra steps; converting
a `.docx` or Google Doc to Markdown silently drops the images; and rich copy-paste from
Google Docs or Notion has nowhere to land, because terminals strip everything but plain
text. The worst case is catastrophic: a Markdown file with base64-inlined images, read as
text, burns **~200k tokens per image** while the model *still can't see the image*.

mmdoc fixes this once, at write time: convert content into a plain folder shape, and the
read side needs nothing special — forever, for every tool and every agent.

## The format in 10 lines

An mmdoc is a directory: **exactly 1** `index.md` (the document) plus **N** co-located
image files at the folder root, referenced by relative path with descriptive alt text.

```
district-analysis/
  index.md          ← exactly 1 entry file: YAML frontmatter + Markdown body
  img-001.png       ← N images (0 or more), referenced as
  img-002.jpg          ![what it shows and why it matters](img-001.png)
```

The **alt text is a greppable one-sentence summary** — `rg "budget allocation"` matches
the reference line, and an agent opens the actual image file only when it needs visual
detail. `grep`, `git`, and every editor already work; no new tooling is required to read one.

## Install

Via Homebrew (includes pandoc):

```sh
brew install hsurick/mmdoc/mmdoc
```

Or from PyPI (then install pandoc yourself):

```sh
uv tool install mmdoc    # or: pip install mmdoc
brew install pandoc
```

Then wire up Claude Code (installs the agent skill + the CLAUDE.md read convention):

```sh
mmdoc setup
```

## 60-second demo

Copy a chunk of a Google Doc — text and images — then:

```sh
mmdoc paste notes/
```

The text lands in `notes/index.md` and the images land as real files
(`notes/img-001.png`, …) next to it. Or skip the clipboard entirely and pull a
link-shared Google Doc directly:

```sh
mmdoc fetch "https://docs.google.com/document/d/<id>/edit"
```

## Commands

| Command | What it does |
|---|---|
| `mmdoc init <name>` | Scaffold a new, empty mmdoc folder with a templated `index.md`. |
| `mmdoc normalize <src>` | Convert a document (`.docx` or base64 Markdown) into an mmdoc folder. |
| `mmdoc paste <target>` | Land the system clipboard (rich text, image, or text) in an mmdoc — appends or creates. |
| `mmdoc clip` | Snapshot the clipboard into a numbered staging dir (reference as `{clip:N}`). |
| `mmdoc fetch <url>` | Download a link-shared Google Doc (no OAuth) and convert it into an mmdoc folder. |
| `mmdoc export <target>` | Export an mmdoc folder to a single shareable file (html, docx, or pdf). |
| `mmdoc validate <target>` | Check that a folder is a well-formed mmdoc; exit non-zero on errors. |
| `mmdoc setup` | Wire mmdoc into Claude Code: install the skill + CLAUDE.md read convention. |

## Agent integration

`mmdoc setup` wires Claude Code in one shot: it installs the bundled workflow skill to
`~/.claude/skills/mmdoc/` and maintains a marker-delimited read-convention block in
`~/.claude/CLAUDE.md` (idempotent; `--dry-run` supported).

The read convention itself is three lines:

- `index.md` holds the text; alt text is a summary — read the image file only when you
  need visual detail.
- Convert before read: never read a `.docx` or a base64-blob `.md` directly into context;
  run `mmdoc normalize` first.
- After editing an mmdoc, run `mmdoc validate <folder>`.

The format is agent-agnostic: paste the same convention into an `AGENTS.md` (or any
equivalent instruction file) and any agent with file tools can work with mmdocs.

## Spec & design docs

- [FORMAT.md](FORMAT.md) — the normative format specification (v0.1).
- [CLI.md](CLI.md) — CLI architecture and command specs.
- [OVERVIEW.md](OVERVIEW.md) — the problem, goal, and build plan.
- [NOTES.md](NOTES.md) — background reasoning and prior-art survey.

## Status

**v0.1.** Clipboard commands (`paste`, `clip`) are **macOS-only** for now (Linux via
`xclip`/`wl-paste` planned). Roadmap:

- `normalize` support for Notion `.zip` exports.
- `normalize` support for loose/messy folders.
- DocLang (`.dclg`/`.dclx`) importer — bridges Docling document-AI pipelines (and PDFs) into mmdoc.
- TextBundle interop — import/export the existing `.textbundle` format.

## License

Apache-2.0. See [LICENSE](LICENSE).
