---
feature_id: FTR-12
title: Markdown Sidecars
category: Documents
optional: true
depends_on: none
registry_refs: [5.32, 9.01, 9.02, 9.03, 9.04, 9.05]
---

# Markdown Sidecars

## 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).

## 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
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?