What this is
On-demand `.md` companion files created from PDFs and other non-indexable documents -- full, faithful, page-by-page content with image and signature descriptions -- so PDF content becomes searchable and usable without repeatedly opening the binary. Includes the standing "prefer markdown" preference. Optional; most useful for document-heavy projects (legal, research).
install markdown-sidecars
The sections below are the install payload — the directives Claude reads and runs when this feature is installed. Shown here for transparency; a person browsing only needs "What this is" above.
Assess first
- Check whether `admin\AGENT_INSTRUCTIONS.md` already has a MARKDOWN SIDECARS section. If present, confirm and skip. - No upfront setup is required for this feature -- it is a capability the agent offers when a PDF appears, not a folder or file to create now.
Ask, only if needed
Nothing to ask at install time -- proceed directly to Write. (The agent offers sidecars per-PDF at the moment one appears; it does not ask anything during installation.)
Write (payload written into admin\AGENT_INSTRUCTIONS.md)
Add this section to `admin\AGENT_INSTRUCTIONS.md`:
```
* MARKDOWN SIDECARS
Markdown Sidecars are .md companion files created from PDFs and other
non-indexable documents. Available for any PDF in the project. Full
faithful content -- not a summary.
WHEN TO OFFER
User mentions a PDF, drops a PDF, or asks to work with PDF content. Offer
once: "I can create a markdown sidecar for that -- full text, page numbers,
and image descriptions. Makes it searchable and usable going forward. Want
one?" Do not repeat the offer if declined.
COMMAND: "create sidecar for [filename]"
SIDECAR STRUCTURE
Header: source file path, source type, total pages, creation date,
created by (agent/session context)
Body: page-by-page sections with explicit ## Page N headers, verbatim
OCR text
Images: full description of every image -- text within images
transcribed; signatures noted as "Handwritten signature, appears to be
[name if legible -- otherwise UNCLEAR]"; charts/graphs described by
title and visible data; photos described; unclear images marked
[UNCLEAR IMAGE -- insufficient resolution]
HIGH INTEGRITY RULES -- NON-NEGOTIABLE
1. No assumptions -- unclear text marked [UNCLEAR] or [ILLEGIBLE], never
guessed
2. No skipping -- every page captured, every visible element noted
3. No summarizing -- transcribe faithfully; do not interpret or condense
4. Images -- every image described fully; signatures identified explicitly
5. Page numbers -- every section labeled with its source page number
6. Low confidence -- uncertain extractions flagged [LOW CONFIDENCE: ...]
7. Partial images -- note exactly what is visible; never report partial
content as complete
These rules are non-negotiable regardless of document complexity.
NAMING & LOCATION
Filename: [source_filename]_sidecar.md
Location: same folder as the source file
Example: discovery\depo_smith_2024-03-15_sidecar.md
MARKDOWN PREFERENCE -- STANDING RULE
Prefer .md for all working documents, drafts, notes, internal reference
files. Markdown indexes well, is portable, searchable, version-control
friendly.
| Use case | Preferred format |
| Working drafts, notes, briefs | .md |
| User-requested Word output | .docx |
| Final client / external delivery | .pdf |
| Internal reference files | .md |
Reserve .docx for explicitly requested Word output only.
Reserve .pdf for final delivery -- never edit a PDF directly (see PDF RULE).
```Confirm
Confirm: Markdown Sidecars are enabled -- the agent will offer to turn any PDF into a full, faithful `.md` companion, and prefers markdown for working files. Want to install another, or is that everything for now?