library-os

name	library-os
description	Library OS — the persistent digital library system. Use when adding a book, deepening an existing review, extracting insights from handwritten notes / highlights / photos, or when the user wants to build their own library on their site. Handles the full workflow from capture to publish.

Library OS

The open-source Library Intelligence System. Captures everything you read into a permanent, intelligent, citation-ready knowledge library on your own website.

When to use this skill

• User mentions adding a book, book review, reading list, library
• User shares handwritten notes, book highlights, Kindle exports, or a photo of notes
• User says "I just finished [book]" or "let me capture this book"
• User asks about the book system, /library/*, or wants to port it to another site
• User wants to deepen a shallow review into a hub page

Core philosophy

1. Own your library. Kindle highlights die in Kindle. Notion docs scatter. A library on your own site, in git, becomes a permanent asset that compounds for decades.
2. Data schema is the spine. The template is interchangeable; the BookReview type + its sub-types are the interoperable core. Port to any Next.js, Astro, SvelteKit, or even static HTML.
3. Structured, not scraped. Every book is curated — quotes carry chapter references, chapter summaries carry key ideas, related reading carries a reason, not a category tag.
4. AEO-first. Every book page emits BreadcrumbList + Article + Review + FAQPage + Quotation schema. Citation surface is the product.
5. Repeatable, not bespoke. One data schema, one template, one command pipeline. Every new book follows the same path. No snowflakes.

The workflow (canonical)

CAPTURE ──────► EXTRACT ──────► ENRICH ──────► PUBLISH
   │                │                │              │
   ▼                ▼                ▼              ▼
Photo, notes,   quotes[]      continueReading[]   /library/{slug}
Kindle export,  chapters[]    videos[]            (live, SEO+AEO)
voice memo      tldr, faq     + schema

Step 1 — CAPTURE The user provides the raw signal: a book title, a handwritten note photo, a highlights export, a voice memo. If a photo, extract text via vision. If a file, read it.

Step 2 — EXTRACT Run /library-add to create the baseline entry (title, author, categories, 5 key insights, best-for, FAQ, TL;DR, cover). Then run /library-deepen to populate quotes and chapters via the book-distiller subagent.

Step 3 — ENRICH Run /library-research to populate continueReading (external books with why-they-pair rationale) and videos (talks, interviews, lectures).

Step 4 — PUBLISH Commit, sync to production repo, ship. Page goes live at /library/{slug} with the full deep-dive hub: TL;DR, TOC, insights, quotes, chapters, FAQ, continue-reading, videos, related-own-book, Amazon CTA.

The three slash commands

Command	Purpose	Writes to
/library-add	Create a new entry from just a title	data/book-reviews.ts, public/images/library/
/library-deepen	Add quotes + chapters to existing entry	data/book-reviews.ts
/library-research	Add continueReading + videos	data/book-reviews.ts

Run in order. Each is idempotent — running /library-deepen twice just refines the existing quotes/chapters, it does not duplicate.

The subagent

book-distiller — the extraction specialist. Given a book + (optional) source text, returns structured quotes[] and chapters[] matching the exact type shape. Delegated to by /library-deepen so the main conversation stays thin.

See .claude/agents/book-distiller.md for the agent prompt.

The data schema (always the source of truth)

Located at app/books/types.ts:

interface BookReview {
  // Identity
  slug, title, author, coverImage, rating, reviewDate, categories, readingTime

  // Core content (required)
  keyInsights: string[]  // exactly 5
  bestFor: string[]      // 3-4

  // AEO core (optional, strongly recommended)
  tldr?: string
  faq?: Array<{q, a}>
  publicationYear?: number

  // Deep-dive hub (optional — the progressive depth layer)
  quotes?: BookQuote[]                // curated passages
  chapters?: BookChapterSummary[]     // number, title, keyIdea, summary
  continueReading?: RelatedReadingItem[]  // with reason, not algorithm
  videos?: BookVideo[]                // kind, duration, description

  // Wiring
  amazonUrl?: string
  relatedBook?: string     // slug from booksRegistry — links to our own books
  hasCover?: boolean       // gates the next/image render
}

Books without the deep-dive fields render as review-depth. Books with all fields render as full knowledge hubs. One template, progressive depth.

Cross-AI / cross-tool portability

The intelligence is in the schema + workflow, not in any specific AI tool. The same pattern works with:

• Claude Code (native) — the three slash commands + subagent + skill are defined here
• ChatGPT / Claude.ai (web) — paste the extraction prompt from the command file, paste the book details, get structured output, paste into data/book-reviews.ts
• Codex / Cursor / Gemini CLI — read .claude/commands/library-*.md as plain instructions, execute the steps
• Hand-roll — the schema and template work without any AI. Manually curated libraries are valid.

See docs/cross-ai-guide.md in the library-os repo for the prompt-paste versions.

Deployment targets

The template is Next.js App Router (frankx.ai uses this). Adaptations:

• Astro — Port app/library/ to src/pages/library/, use .astro for layout. Data schema unchanged.
• SvelteKit — routes/library/+page.svelte, data unchanged.
• Hugo — static generation, the BookReview[] becomes frontmatter YAML in content/library/*.md.
• Plain HTML — a small build script renders the data to static pages.

The spine — data/book-reviews.ts as a typed array + the JSON-LD schema — is portable.

Index page contract

The library index (/library) shows:

• All reviews sorted by reviewDate DESC (newest first)
• Cards with cover + title + author + star rating + top insight
• "Deep-dive badge" on cards that have quotes/chapters/videos (e.g. "16 quotes · 14 chapters · 5 videos")
• Category filter (optional, client-side)
• CollectionPage + ItemList + BreadcrumbList JSON-LD

Detail page contract

The detail page (/library/{slug}) renders, in order:

1. Back link → /library
2. Header: cover + title + author + stars + category chips
3. TL;DR card (if tldr)
4. Table of Contents (inline anchor nav, sections only shown when data present)
5. Key Insights (5)
6. Quotes Worth Remembering (if quotes)
7. Chapter-by-Chapter accordion (if chapters)
8. Best For
9. FAQ accordion (if faq)
10. Continue Reading grid (if continueReading)
11. Go Deeper — Videos (if videos)
12. "If You Liked This, Read Ours" (if relatedBook matches a slug in booksRegistry)
13. Amazon CTA
14. More from the Library (3 other reviews)

All section IDs are anchor-linkable with scroll-mt-24 for smooth jumps from the TOC.

Quality bar

• No AI-sounding phrases. Blacklist: delve, dive into, it's worth noting, certainly, absolutely, in conclusion, let's explore.
• No fake URLs. If uncertain about a specific video URL, use a YouTube search URL. Better a search than a dead link.
• No blurb-style recommendations. Every continueReading.reason must state a connection, not a summary.
• No chapter fabrication. If the book's chapter list is uncertain, stop and ask for the table of contents. Never invent chapters.
• Cover images from legitimate sources. OpenLibrary (covers.openlibrary.org/b/isbn/{ISBN}-L.jpg) is fair-use for review purposes. Never scrape Amazon product images.

Git workflow

Library changes live in the FrankX dev repo but deploy via the production repo (frankxai/frankx.ai-vercel-website). Standard pattern:

1. Commit library changes in FrankX dev repo (scoped: app/library/, app/books/types.ts, data/book-reviews.ts, public/images/library/)
2. Create isolated worktree from prod origin/main
3. Sync those exact files into the worktree
4. Commit in worktree, push branch, open PR
5. Admin-merge after Vercel preview passes (CI will show pre-existing tech debt — ignore per issue #31)
6. Verify live on frankx.ai

Related

• /library → the live index
• /library/approach → the showcase page explaining the system
• GitHub: library-os repo → open-source template + docs
• Companion skill: book-publishing (for authoring own books)