Skip to content

CLAUDE.md

Latest commit

 

History

History
79 lines (57 loc) · 3.65 KB

CLAUDE.md

File metadata and controls

79 lines (57 loc) · 3.65 KB
Raw

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is the index generation pipeline for Embedded AI, a book published by No Starch Press (NSP). The goal is to produce Word XE field codes embedded in .docx chapter files that InDesign can consume to generate the final book index.

The manuscript has 18 source files in manuscript/ (intro, 16 chapters, appendix). No scripts have been implemented yet.

Pipeline Architecture

The pipeline is strictly two-phase:

Phase 1 — Editorial (human judgment + Claude as thinking partner):

  1. summaries/ch_N_index_summary.md — per-chapter structured summaries
  2. seed_list/ — master term registry (single source of truth for all index decisions)
  3. manifests/ch_N_manifest.json — JSON insertion manifests generated from seed list

Phase 2 — Mechanical (deterministic scripts, no editorial judgment):

  • scripts/validate_manifest.py — validates all anchors exist in the .docx
  • scripts/insert_xe_tags.py — inserts XE field codes and writes to tagged/

The insertion script must never make editorial decisions. If an anchor cannot be found, it reports the miss and skips — it does not guess.

Scripts (when implemented)

# Validate manifest anchors against a chapter
python scripts/validate_manifest.py manifests/ch_N_manifest.json manuscript/ch_N_*.docx

# Insert XE tags into a chapter
python scripts/insert_xe_tags.py manuscript/ch_N_*.docx manifests/ch_N_manifest.json tagged/ch_N_tagged.docx

Manifest Format

{
  "term": "finite state machines",
  "subentry": "orientation detection",
  "anchor": "FSM to classify the orientation",
  "type": "main"
}

Anchors are short, unique text snippets near the insertion point — never paragraph numbers or byte offsets. Manifests survive manuscript edits; absolute positions do not.

Seed List Structure

Files under seed_list/ are split by category because the consistency pass scans them independently:

  • People — enforces Last, First format; all named persons in main text are mandatory
  • Acronyms — every acronym must appear twice: once under the acronym, once under the spelled-out form
  • Cross-references — see and see also entries; orphans are caught before tag insertion
  • Style decisions (docs/style_decisions.md) — every naming and hierarchy choice is recorded here to prevent re-litigation

NSP / XE Tag Rules

  • XE must be capitalised in field codes — lowercase xe will not import into InDesign
  • Subentries use colon delimiters: { XE "main entry:subentry" }, three levels maximum
  • Page ranges require paired tags with identical term strings (case- and space-sensitive): { XE "term startRange" } … { XE "term endRange" }
  • Cross-references: { XE "FSM:see finite state machines" }, { XE "sensor fusion:see also Kalman filter" }
  • Capitalisation follows manuscript usage — Bullion and bullion are separate entries
  • Character styles (Italic, Literal) are lost in the XE round-trip; NSP applies them manually after InDesign generates the index
  • Target index length: 5–8% of manuscript word count (~5,000–8,000 words for a 100k manuscript)
  • Alphabetisation: letter-by-letter (not word-by-word)
  • Style authority: Chicago Manual of Style, 18th Edition, Chapter 15

Git Commit Convention

summary(ch6): add Chapter 6 index summary
seed: merge Chapter 6 terms, resolve FSM vs finite state machines
manifest(ch6): generate insertion manifest
tag(ch6): insert XE tags into Chapter 6
docs: update style_decisions.md with FSM naming rule

Tag releases: v0.1-seed-complete, v0.2-all-tagged, v1.0-final.