# AGENTS.md — Book Print Obsidian Plugin

This document defines the permanent product requirements, design guidelines, architecture rules, and operational principles for the **Book Print Obsidian Plugin**. All AI agents and software engineers working on this codebase must adhere strictly to these rules.

---

# 1. Product Philosophy & Scope Boundaries

## Primary Mission
> Make printing a beautiful physical book from Obsidian notes almost as easy as printing a document.

The plugin provides a physical book printing feature built directly into Obsidian Desktop. 
The intended end-to-end user flow:
**Select notes → Edit manuscript → Preview book → Choose cover → Choose paperback/hardcover → See price → Pay → Book is printed and shipped**

## What the User Decides
* Which notes?
* What order?
* What title?
* What author?
* What imprint?
* Where should manual page breaks (`///`) occur?
* Generic cover or custom artwork?
* Paperback or hardcover?
* How many copies?
* Where should it ship?

Everything else is standardized and automated.

## What is NOT in Scope (Strictly Forbidden in MVP)
* No Adobe InDesign or complex desktop publishing controls
* No EPUB, Kindle, or digital ebook export
* No Amazon publishing or ISBN purchasing
* No public marketplace or social sharing
* No AI text writing, AI rewriting, or AI cover generation
* No cream paper, color interiors, dust jackets, cloth covers, spiral/saddle-stitch binding
* No arbitrary trim sizes (6 × 9 inches ONLY in v1)
* No custom fonts, typography controls, or custom CSS styling for users
* No mobile platform compromise (Obsidian Desktop only)

---

# 2. Key Architecture Principles

1. **Desktop First & Offline Local PDF Rendering**:
   - PDF generation happens locally via Electron's `webContents.printToPDF()`.
   - Zero per-render cloud cost. Fast editing, complete privacy.
   - Cloud PDF rendering must NOT be introduced unless local rendering is mathematically or physically impossible.

2. **Privacy Architecture**:
   - The user's notes remain local until an intentional physical book order is placed.
   - Markdown manuscripts are never uploaded to the backend server.
   - When ordering, only the compiled interior PDF, cover PDF, required book metadata, and shipping address are securely transmitted.

3. **Backend Responsibilities**:
   - Thin TypeScript backend (API service).
   - Manages Stripe payments, Lulu Print API interaction, signed S3/R2 storage URLs, quotes, and webhooks.
   - Zero Lulu or Stripe API secret keys inside the distributed plugin client.

4. **Non-Destructive Manuscript Editing**:
   - Combining source notes creates an independent **Book Project** working manuscript.
   - Edits, additions, deletions, and `///` page breaks in the Book Project manuscript NEVER alter the original Obsidian notes in the vault.

5. **Reference UX Mental Model**:
   - Borrows the two-panel interface from *Advanced PDF Export* by ShrekBytes:
     **Editable Markdown manuscript on left → Paginated 6 × 9 book preview on right**.

---

# 3. Fixed Physical Book Specifications

* **Trim Size**: 6 × 9 inches (152.4 × 228.6 mm) exactly.
* **Interior**: Black-and-white interior on white paper.
* **Binding Choices**: 
  1. Paperback (Perfect-bound softcover)
  2. Hardcover (Printed casewrap hardcover)
* **Typography**:
  - Primary Font: **Libre Caslon Text** (SIL Open Font License), bundled locally.
  - Body Text: 12 pt Regular, ~15–16 pt line height.
  - Heading 1: 24 pt Bold (starts on a new page by default).
  - Heading 2: 18 pt Bold.
  - Heading 3: 14 pt Bold.
  - Heading 4: 12 pt Bold.
  - Blockquotes: 11 pt Italic.
  - Footnotes & Page Numbers: 9–10 pt.
* **Page Margins & Geometry**:
  - Gutter / Inside: 0.80–0.85 in
  - Outside: 0.60–0.70 in
  - Top: 0.70–0.75 in
  - Bottom: 0.75 in
  - Bleed: 0.125 in (3.175 mm) where required by printer specs.

---

# 4. Manual Page Break Convention

- A line containing only `///` forces a page break.
- Syntactically:
  ```text
  ///
  ```
- The marker `///` is stripped from final printed output and rendered visually as `── PAGE BREAK ──` in the editor.

---

# 5. Monorepo Project Structure

```text
book-print-obsidian/
  apps/
    obsidian-plugin/     # Main Obsidian Desktop plugin codebase
    api/                 # Express / Fastify / Node API service
  packages/
    shared/              # Shared types, validation schemas, order state machine
    markdown/            # Markdown compiler, wikilink parser, frontmatter generator
    book-layout/         # CSS paged media rules, Libre Caslon font assets, 6x9 layout engine
    pdf/                 # Electron printToPDF runner, page geometry verifier
    printer/             # Lulu API client & MockPrintProvider implementation
    storage/             # Local storage & S3 / R2 object storage provider abstractions
  docs/
    integration-notes.md # Detailed technical & API integration documentation
```

---

# 6. Quality & Security Checklist for Developers

- **TypeScript Strict Mode**: Enabled across all packages.
- **No Direct Credential Storage**: Secrets belong in backend `.env`.
- **Validation**: All PDFs must be verified for dimensions (152.4 × 228.6 mm) and page count before Lulu validation and order checkout.
- **Idempotency**: Webhook handling for Stripe and Lulu must be strictly idempotent to prevent duplicate charges or print submissions.
