Add README with plan overview, architecture, and document index

README.md

@@ -0,0 +1,69 @@
+# 3-Year Plan: Shopfloor IT/OT Transformation
+
+A 3-year plan for transforming and enhancing shopfloor IT/OT interfaces and data collection — bridging IT and OT layers, improving operator interfaces, and upgrading data collection pipelines.
+
+## Vision
+
+A **stable, single point of integration between shopfloor OT and enterprise IT**.
+
+## Three Pillars (binary at end of plan)
+
+1. **Unification** — 100% of sites on the standardized stack (OtOpcUa + ScadaBridge + Redpanda + SnowBridge + Snowflake/dbt).
+2. **Analytics / AI Enablement** — machine data in Snowflake with a ≤15-minute analytics SLO; at least one "not possible before" use case in production.
+3. **Legacy Retirement** — zero remaining bespoke IT/OT integration paths outside ScadaBridge.
+
+## Key Architecture
+
+```
+Layer 1  Equipment (PLCs, controllers, instruments)
+Layer 2  OtOpcUa (unified site-level OPC UA — single session per equipment, two namespaces)
+Layer 3  SCADA (Aveva System Platform + Ignition)
+Layer 4  ScadaBridge (sole IT/OT crossing point)
+         ─── IT/OT Boundary ───
+         Enterprise IT (Camstar, Delmia, Snowflake, Power BI, SnowBridge)
+```
+
+The plan also declares a **Unified Namespace (UNS)** composed of OtOpcUa + Redpanda + canonical model in `schemas` repo + dbt curated layer, with a 5-level naming hierarchy standard (Enterprise → Site → Area → Line → Equipment).
+
+## Plan Documents
+
+| File | Purpose |
+|---|---|
+| [`current-state.md`](current-state.md) | Snapshot of today's systems, integrations, and pain points |
+| [`goal-state.md`](goal-state.md) | Target end-state: architecture, components, success criteria, UNS, canonical model |
+| [`roadmap.md`](roadmap.md) | 7 workstreams x 3 years migration grid |
+| [`STATUS.md`](STATUS.md) | Working-session bookmark — where we left off, pending items |
+
+### Component Detail Files
+
+| File | Purpose |
+|---|---|
+| [`current-state/legacy-integrations.md`](current-state/legacy-integrations.md) | Pillar 3 denominator: 3 legacy IT/OT integrations to retire |
+| [`current-state/equipment-protocol-survey.md`](current-state/equipment-protocol-survey.md) | Year 1 protocol survey template (also produces UNS hierarchy snapshot) |
+| [`goal-state/digital-twin-management-brief.md`](goal-state/digital-twin-management-brief.md) | Digital twin management conversation brief (completed) |
+
+### Output Generation
+
+| File | Purpose |
+|---|---|
+| [`outputs/README.md`](outputs/README.md) | How to regenerate PPTX + PDF from plan source |
+| [`outputs/presentation-spec.md`](outputs/presentation-spec.md) | 18-slide mixed-stakeholder deck structure |
+| [`outputs/longform-spec.md`](outputs/longform-spec.md) | Faithful-typeset PDF structure |
+
+Trigger: `regenerate outputs`, `regenerate presentation`, or `regenerate longform` in a Claude Code session.
+
+## Conventions
+
+- Everything in markdown — no proprietary formats.
+- `_TBD_` marks gaps that still need filling.
+- Decisions are captured inline with rationale; don't re-open without new information.
+
+## Working with Claude Code
+
+This repo includes a [`CLAUDE.md`](CLAUDE.md) file that orients Claude Code sessions to the plan's structure and conventions. Resume work with:
+
+```
+claude --resume <session-id>
+```
+
+or start a new session in this directory — `CLAUDE.md` and `STATUS.md` provide enough context to pick up where the last session left off.