# Project Context

This directory contains a **3-year plan for transforming and enhancing shopfloor IT/OT interfaces and data collection**.

Work in this repo focuses on planning, designing, and tracking the multi-year roadmap for modernizing shopfloor systems — bridging IT and OT layers, improving operator interfaces, and upgrading data collection pipelines.

## Structure

Plan content lives in markdown files at the repo root to keep it easy to read and update:

- [`current-state.md`](current-state.md) — snapshot of today's shopfloor IT/OT systems, integrations, data collection, and pain points.
- [`goal-state.md`](goal-state.md) — target end-state at the close of the 3-year plan, including success criteria.
- [`roadmap.md`](roadmap.md) — migration plan / sequencing from current state to goal state over the 3 years.
- [`status.md`](status.md) — working-session bookmark; records where we left off and the top pending items. Not authoritative plan content.

### Component detail files

- [`current-state/legacy-integrations.md`](current-state/legacy-integrations.md) — authoritative inventory of **bespoke IT↔OT integrations** that cross ScadaBridge-central outside ScadaBridge. Denominator for pillar 3 retirement.
- [`goal-state/digital-twin-management-brief.md`](goal-state/digital-twin-management-brief.md) — meeting-prep artifact for the management conversation that turns "we want digital twins" into a scoped response. Parallel structure to `goal-state.md` → Strategic Considerations → Digital twin.
- [`schemas/`](schemas/) — **Canonical OT equipment definitions seed** (temporary location — see `schemas/README.md`). JSON Schema format definitions, FANUC CNC pilot equipment class, UNS subtree example, and documentation. Contributed by the OtOpcUa team; ownership TBD. To be migrated to a dedicated `schemas` repo once created.

### Output generation pipeline

- [`outputs/`](outputs/) — **repeatable PPTX + PDF generation** over the plan markdown. Entry point: [`outputs/README.md`](outputs/README.md) (trigger phrases + regeneration checklist). Structure anchors: [`outputs/presentation-spec.md`](outputs/presentation-spec.md) for the 18-slide mixed-stakeholder deck and [`outputs/longform-spec.md`](outputs/longform-spec.md) for the faithful-typeset long-form PDF. Outputs live under `outputs/generated/`; do not hand-edit them.

**Quick reference — regenerating outputs:**
- `regenerate presentation` — rebuilds the 18-slide PPTX from current plan source files per `outputs/presentation-spec.md`
- `regenerate longform` — rebuilds the PDF per `outputs/longform-spec.md` (not yet run)
- `regenerate outputs` — both
- **To change slide structure:** edit `outputs/presentation-spec.md`, then regenerate. Don't edit the PPTX directly.
- **To change content:** edit the source plan files (`current-state.md`, `goal-state.md`, `roadmap.md`, etc.) — the next regeneration picks up changes automatically.
- **Workspace:** `outputs/workspace/` contains the HTML slides and generation JS script from the last run.

As the plan grows, add further markdown files and link them from here.

## Breaking out components

Individual components (a system, an interface, a data pipeline, an initiative) often need more detail than fits inline. When a section in `current-state.md` or `goal-state.md` outgrows a few paragraphs:

1. Create a dedicated file under a topical subdirectory, e.g.:
   - `current-state/<component>.md`
   - `goal-state/<component>.md`
   - `components/<component>.md` (when it spans both states)
2. Leave a short summary in the parent file and link to the detail file.
3. Keep filenames lowercase-kebab-case so they're easy to reference.

## Conventions

- Keep everything in markdown — no proprietary formats.
- Prefer editing existing files over adding new ones; split a file only when it gets unwieldy or when a component needs its own detail page (see above).
- Use `_TBD_` placeholders for sections that aren't yet filled in, so gaps stay visible.