3yearplan/outputs/longform-spec.md

Longform Spec — Faithful Typeset PDF

The structure anchor for generated/plan-longform.pdf. Every regeneration reads this file first and produces a PDF that renders the current plan markdown as a typeset document with cover, TOC, chapters, and appendices. Edit this file to change PDF structure; do not edit prompts, do not edit the source plan files.

Meta

Property	Value
Type	Faithful typeset (option (a) from the design brainstorm). Structure and headings map 1:1 from source. No curated narrative reshaping.
Audience	Anyone reading the plan standalone — new stakeholders, archival readers, anyone handed the plan without having followed the day-to-day authoring.
Expected length	Roughly 50–80 pages depending on rendering density.
Theme	document-skills:theme-factory default professional theme (serif body font). Override by adding a **Theme override:** line here.
Page size	US Letter (8.5" × 11"). Change to A4 if distribution is primarily non-US.
Margins	1" on all sides
Running header	Chapter title (left-aligned) · "Shopfloor IT/OT Transformation — 3-Year Plan" (right-aligned)
Running footer	Page number (center) · As-of date (right)
Title on cover	"Shopfloor IT/OT Transformation"
Subtitle on cover	"3-Year Plan"
Cover as-of line	"As of {{regeneration-date}}"
Cover abstract	A single paragraph lifted verbatim from ../goal-state.md → Vision (the opening paragraph). Do not paraphrase.

Document structure

Cover page                         — title, subtitle, as-of date, abstract
Table of Contents                  — auto-generated, two levels deep
Chapter 1 — Current State          (source: ../current-state.md)
Chapter 2 — Goal State             (source: ../goal-state.md)
Chapter 3 — Roadmap                (source: ../roadmap.md)
Appendix A — Legacy Integrations Inventory  (source: ../current-state/legacy-integrations.md)

Chapter / appendix file-to-source mapping:

Label	Title	Source file
Chapter 1	Current State	../current-state.md
Chapter 2	Goal State	../goal-state.md
Chapter 3	Roadmap	../roadmap.md
Appendix A	Legacy Integrations Inventory	../current-state/legacy-integrations.md

Explicitly excluded

These files are not part of the PDF — do not include them even if they seem relevant:

File	Why excluded
../CLAUDE.md	Repo meta — instructions for Claude, not plan content.
../status.md	Working bookmark — a session-state artifact, not authoritative plan content.
../goal-state/digital-twin-management-brief.md	Meeting prep artifact. Its own header explicitly says it is not plan content.
./README.md, ./DESIGN.md, ./presentation-spec.md, ./longform-spec.md, ./IMPLEMENTATION-PLAN.md, ./run-log.md	Output pipeline files — the pipeline does not document itself inside its own output.
./diagrams/*, ./generated/*	Output pipeline artifacts.

If a new plan file is added to the repo and should be in the PDF, add it here, under Document structure, as a new chapter or appendix — not in the source file and not in the prompt.

Transformations applied during rendering

The narrow set of changes applied to source markdown when producing the PDF. Source markdown files are not edited — transformations are applied at render time.

1. File H1 → chapter/appendix title

# Current State (the first line of current-state.md) becomes the chapter title "Chapter 1 — Current State" on the chapter's opening page. The H1 is consumed by the chapter heading; it does not appear a second time in the body.

2. Heading numbering

All ##, ###, #### headings receive section numbers:

• ## → N.M where N = chapter number, M increments per ## within the chapter
• ### → N.M.K
• #### → N.M.K.L

Example: ## Systems & Interfaces in Chapter 1 becomes 1.2 Systems & Interfaces.

Numbering is added at render time; source markdown remains unchanged. Numbering is applied to body text but not to the TOC (TOC uses unnumbered section titles for readability).

3. Inter-file link normalization

Markdown links between plan files are resolved to section references in the rendered PDF:

Source link form	Rendered form
[current-state.md](current-state.md)	"see Chapter 1 — Current State"
[goal-state.md](goal-state.md)	"see Chapter 2 — Goal State"
[roadmap.md](roadmap.md)	"see Chapter 3 — Roadmap"
[legacy-integrations.md](current-state/legacy-integrations.md)	"see Appendix A — Legacy Integrations Inventory"
[equipment-protocol-survey.md](current-state/equipment-protocol-survey.md)	Render as plain text — file removed. Log as warning.
Intra-file anchor links like [X](#section-name)	Rendered as internal PDF cross-reference to the numbered section (e.g., "see §1.2")
Links to excluded files (e.g., status.md, digital-twin-management-brief.md)	Rendered as plain text — the link target is dropped, the link text stays. Logged as a warning in the run log.
External links (http://, https://)	Rendered as clickable external links, unchanged.
Unresolvable links (file not found)	Rendered as plain text, logged as a warning in the run log. Do not silently drop.

4. _TBD_ marker highlighting

Every occurrence of _TBD_ in the source becomes a visual callout in the rendered PDF:

• Inline _TBD_ tokens get a colored background (theme-appropriate warning color)
• A small margin icon (⚑ or similar) in the left margin on lines containing a TBD
• TBDs remain readable — the goal is visibility, not obstruction

This makes the "gaps stay visible" convention from ../CLAUDE.md → Conventions actually visible on paper.

5. ASCII / text diagrams preserved

The Layered Architecture text diagram in goal-state.md (and any similar text diagrams elsewhere) renders as a monospace code block with a subtle border. Option (a) faithful typeset explicitly accepts this — proper visual diagrams live in the PPTX, not the PDF.

6. Tables preserved (with multi-page support)

Markdown tables render as PDF tables with row-level borders and header-row emphasis. Tables that exceed one page split cleanly at row boundaries, with the header row repeated at the top of each continuation page. document-skills:pdf handles this natively.

Specific large tables to expect:

• ../roadmap.md → The grid (7 workstreams × 3 years) — likely spans 2–3 pages
• ../current-state/legacy-integrations.md → per-row integration detail tables (one per integration)
• ../current-state/equipment-protocol-survey.md → field schema table, classification table, rollup views

7. Code blocks preserved

Fenced code blocks in the source (for example, the directory-structure dot block in ../goal-state.md or the structure trees in this file) render as monospace blocks with a light background. Line wrapping preferred over horizontal scroll.

8. Block quotes preserved

Markdown > block quotes render as indented italic or colored blocks per the theme. Several key notes in the source (file headers, carve-outs) use block quotes and their emphasis is load-bearing.

9. Emphasis preserved

**bold**, *italic*, and `inline code` all render as expected. The source uses these deliberately (especially bold for decisions and vocabulary terms) — preserve fidelity.

Front matter

Cover page

[Large type]        Shopfloor IT/OT Transformation
[Medium type]       3-Year Plan

[Small type]        As of {{regeneration-date}}

[Body paragraph, centered or full-width]
{{abstract — verbatim from ../goal-state.md → Vision, opening paragraph}}

Table of Contents

• Auto-generated from chapter and appendix headings
• Two levels deep: chapter titles + ## headings within each chapter
• Unnumbered in the TOC for readability (numbering appears in body)
• Page numbers right-aligned
• Leaders (.....) between heading text and page number
• Chapters and appendices visually distinguished (slight indent, different weight, or section label)

Back matter

• No index. Generating a useful index requires curation; automated indexing produces noise. Skip for the first pass.
• No glossary. Plan vocabulary (OtOpcUa, ScadaBridge, SnowBridge, Redpanda, etc.) is defined at first use in the source. If readers need a glossary, that's a future enhancement.

Editing this spec

• Structural changes go here — chapter order, appendix additions, cover layout, page setup, transformation rules.
• Content changes go in the source — typos, new sections, corrections to the plan. The next regeneration picks them up automatically.
• Theme / page-setup changes go in the Meta section at the top of this file. Override with a **Theme override:** or **Page size override:** line.
• Never hand-edit generated/plan-longform.pdf. It is overwritten on the next regeneration.

Planned follow-ups (not first-pass scope)

These are deliberately deferred:

• Curated executive-narrative PDF (option (b) from the design brainstorm) — a second output shaped as a standalone written report with intro, argument flow, transitions. Would live at generated/plan-narrative.pdf with its own narrative-spec.md.
• Bilingual rendering — if the plan ever serves a non-English audience.
• Redacted variant — a version with sensitive detail removed, for external stakeholders.
• Date-stamped archival copies — generated/plan-longform-YYYY-MM-DD.pdf alongside the current one, so the history of the plan is preserved as a series of snapshots.

None of these require changes to the current spec; add them when/if they become real requirements.