diff --git a/specs/InteractionHubFrameworkSpecification_v0.1.md b/specs/InteractionHubFrameworkSpecification_v0.1.md
new file mode 100644
index 0000000..3f5a415
--- /dev/null
+++ b/specs/InteractionHubFrameworkSpecification_v0.1.md
@@ -0,0 +1,923 @@
+InteractionHubFramework
+
+*Inter*
+
+# Interaction Hub Framework (IHF)
+
+*Formal Specification with Phased Implementation Plan*
+
+**Version:** 0.1
+**Status:** Draft Foundation Specification
+**Purpose:** Establish a governed, observable, antifragile interaction substrate for hub-based AI-enabled software systems.
+
+---
+
+## 1. Definition
+
+The **Interaction Hub Framework (IHF)** is a platform framework for building **commentable, observable, governable, and evolvable user interaction systems**.
+
+It provides a stable core for:
+
+* addressing UI elements as governed platform assets
+* capturing user feedback and interaction signals in context
+* transforming observed friction and intent into structured requirements
+* connecting requirements to decisions, implementations, deployments, and outcomes
+* supporting multiple evolving UI technologies without losing semantic continuity
+
+The IHF is intended to serve as the **interaction substrate** of a hub-based AI factory, especially in environments where product development, operations, governance, finance, security, and AI-assisted workflows interact continuously.
+
+---
+
+## 2. Design Intent
+
+The framework is designed to support the following long-term properties:
+
+**Stable semantic core**
+UI technologies may change, but interaction semantics, traceability, and governance remain stable.
+
+**Antifragility**
+The system should improve through systematically captured friction, confusion, unmet expectations, and emergent user needs.
+
+**Observability by design**
+Interaction, feedback, and governance events are first-class operational signals.
+
+**Governance by design**
+Requirements, decisions, policy concerns, and implementation consequences remain linked and auditable.
+
+**Agent compatibility**
+AI agents should be able to inspect, interpret, propose, implement, review, and monitor changes within explicit boundaries.
+
+**Framework independence at the edge**
+The core must not be irreversibly coupled to a specific long-term frontend framework.
+
+---
+
+## 3. Context
+
+The Interaction Hub Framework sits at the intersection of:
+
+* application platform architecture
+* requirements engineering
+* interaction design systems
+* observability engineering
+* workflow and governance systems
+* agentic software delivery
+
+It is especially suitable for:
+
+* control surfaces
+* dashboards
+* internal platforms
+* AI-assisted operations portals
+* workflow-heavy enterprise systems
+* hub-based socio-technical systems
+* platforms where user feedback must become implementation input
+
+---
+
+## 4. Scope
+
+### 4.1 In Scope
+
+The IHF includes:
+
+* widget identity and lifecycle governance
+* interaction event capture
+* comment and annotation capture
+* structured feedback classification
+* requirement candidate generation and linking
+* decision ledger integration
+* implementation traceability
+* rollout and outcome observation
+* realtime operational interaction surfaces
+* cross-hub integration of interaction signals
+* AI-assisted distillation and prioritization workflows
+* platform APIs and conventions for framework-agnostic UI integration
+
+### 4.2 Out of Scope
+
+The IHF does not attempt to define:
+
+* a complete universal frontend framework
+* a pixel-level visual design system
+* a full product management methodology
+* a replacement for DevOps observability tooling
+* unrestricted autonomous decision-making by AI agents
+* a mandatory single UI technology for all surfaces
+
+---
+
+## 5. Core Architectural Principle
+
+The core principle of IHF is:
+
+> **Every meaningful interaction surface must be semantically addressable, contextually observable, governable, and evolvable.**
+
+This means that a renderable UI unit is not treated merely as markup or code. It is treated as a **governed interaction artifact**.
+
+---
+
+## 6. Key Concepts
+
+## 6.1 Hub
+
+A **Hub** is a bounded domain of responsibility within the wider platform.
+
+Examples:
+
+* Dev Hub
+* Ops Hub
+* Sec Hub
+* Fin Hub
+* State Hub
+* Governance Hub
+
+A Hub owns capabilities, policies, widgets, workflows, and observation surfaces within its domain.
+
+## 6.2 Widget
+
+A **Widget** is the smallest semantically governable interaction unit that is intentionally addressable by the framework.
+
+A Widget may be:
+
+* a chart
+* a status panel
+* a form
+* a table
+* an action control
+* a composite operator panel
+* a workflow step display
+* an embedded recommendation block
+* a chat interaction region
+* a diff or review element
+
+A Widget is not defined by its visual implementation alone. It is defined by its **semantic role and governed identity**.
+
+## 6.3 Widget Envelope
+
+A **Widget Envelope** is the metadata boundary attached to a Widget that enables observation and governance.
+
+A Widget Envelope should carry at least:
+
+* `widget_id`
+* `widget_type`
+* `hub_id`
+* `capability_ref`
+* `view_context`
+* `state_ref` or equivalent context reference
+* `policy_scope`
+* `widget_version`
+* `implementation_ref`
+* optional `experiment_variant`
+* optional `requirements_thread_ref`
+
+## 6.4 Interaction Event
+
+An **Interaction Event** is a recorded user or agent interaction involving a Widget.
+
+Examples:
+
+* viewed
+* focused
+* clicked
+* submitted
+* abandoned
+* retried
+* failed
+* commented
+* flagged_confusing
+* flagged_helpful
+* blocked_by_policy
+* escalated
+* accepted_recommendation
+* rejected_recommendation
+
+## 6.5 Annotation
+
+An **Annotation** is a structured comment or signal attached to a Widget, a Widget region, a Widget state, or an interaction sequence.
+
+Annotations are richer than free-form comments and may include classification, intensity, intent, and contextual linkage.
+
+## 6.6 Requirement Candidate
+
+A **Requirement Candidate** is a structured artifact derived from observed interaction signals, annotations, or analysis.
+
+It may represent:
+
+* a usability issue
+* a documentation gap
+* a missing capability
+* a policy conflict
+* a trust deficit
+* a workflow bottleneck
+* an accessibility concern
+* a governance concern
+* a product opportunity
+
+## 6.7 Decision Record
+
+A **Decision Record** captures the resolution, rejection, deferral, or transformation of a Requirement Candidate or related issue.
+
+## 6.8 Outcome Signal
+
+An **Outcome Signal** is an observed post-change indicator showing whether a change improved or degraded the system.
+
+Examples:
+
+* reduced abandonment
+* improved task completion
+* reduced confusion flags
+* increased operator trust
+* increased escalation rate
+* reduced policy violation frequency
+
+---
+
+## 7. Intended System Role
+
+Within the broader hub-based AI factory, IHF serves as the **interaction core** that connects:
+
+* user experience
+* operator workflows
+* governance
+* observability
+* requirements evolution
+* AI-assisted implementation
+
+It is the layer where interaction becomes inspectable and improvable instead of disappearing into unstructured usage.
+
+---
+
+## 8. Alignment with Orthogonal Architecture
+
+## 8.1 Stack Dimension
+
+IHF primarily occupies:
+
+* application platform layer
+* workflow and governance services layer
+* observability-integrated interaction layer
+
+## 8.2 Quality Dimension
+
+IHF strongly concerns:
+
+* observability
+* auditability
+* evolvability
+* governability
+* security
+* traceability
+* usability
+* resilience
+
+## 8.3 Logic Dimension
+
+IHF spans:
+
+* interaction semantics
+* workflow coordination
+* requirements distillation
+* decision traceability
+* feedback processing
+* cross-hub visibility
+
+---
+
+## 9. Core Modules
+
+## 9.1 Widget Registry Module
+
+Maintains the authoritative catalog of Widgets.
+
+Responsibilities:
+
+* widget registration
+* semantic identity assignment
+* ownership tracking
+* lifecycle state management
+* versioning
+* deprecation relationships
+* capability linkage
+* policy scope linkage
+
+## 9.2 Interaction Capture Module
+
+Captures structured interaction events.
+
+Responsibilities:
+
+* event ingestion
+* event validation
+* actor attribution
+* contextual enrichment
+* correlation with widget and view context
+* storage in append-only form where appropriate
+
+## 9.3 Annotation Module
+
+Captures free-form and structured comments tied to interaction surfaces.
+
+Responsibilities:
+
+* widget-level annotation
+* state-level annotation
+* region-level annotation where supported
+* category assignment
+* severity or intensity assignment
+* actor identity linkage
+* artifact linkage
+
+## 9.4 Requirements Distillation Module
+
+Transforms raw feedback into structured requirement artifacts.
+
+Responsibilities:
+
+* clustering
+* duplicate detection
+* issue framing
+* proposal drafting
+* metadata enrichment
+* confidence scoring
+* reviewer workflow integration
+
+## 9.5 Governance Ledger Module
+
+Provides traceable decision and policy linkage.
+
+Responsibilities:
+
+* record decisions
+* connect decisions to requirements
+* connect requirements to implementations
+* connect implementations to deployments and outcomes
+* preserve reviewable justification
+
+## 9.6 Outcome Observation Module
+
+Observes changes after rollout.
+
+Responsibilities:
+
+* compare pre-change and post-change signals
+* track effect metrics
+* flag regressions
+* support experiment and rollout review
+
+## 9.7 Realtime Coordination Module
+
+Supports operationally live hub surfaces.
+
+Responsibilities:
+
+* realtime widget refresh
+* queue and workflow updates
+* collaborative review surfaces
+* live issue boards
+* moderation and triage views
+
+## 9.8 Agent Integration Module
+
+Provides boundaries for AI-assisted work.
+
+Responsibilities:
+
+* issue summarization
+* requirement drafting
+* clustering and prioritization support
+* traceability assistance
+* proposal generation
+* bounded remediation suggestions
+
+---
+
+## 10. Canonical Artifact Types
+
+The framework should standardize at least these artifact types:
+
+* Widget
+* WidgetVersion
+* InteractionEvent
+* Annotation
+* AnnotationThread
+* RequirementCandidate
+* Requirement
+* DecisionRecord
+* ImplementationChange
+* DeploymentRecord
+* OutcomeSignal
+* PolicyReference
+* CapabilityReference
+* ViewContext
+
+These artifacts should be linkable by stable identifiers.
+
+---
+
+## 11. Canonical Traceability Chain
+
+The framework should support the following traceability chain:
+
+`Widget -> InteractionEvent / Annotation -> RequirementCandidate -> DecisionRecord -> ImplementationChange -> DeploymentRecord -> OutcomeSignal`
+
+This chain is central to governance and antifragility.
+
+---
+
+## 12. Architectural Constraints
+
+The following constraints apply to all implementations of IHF.
+
+### 12.1 Stable Semantic Identity
+
+Widget identity must be stable across implementation changes where semantic continuity remains.
+
+### 12.2 Separation of Semantics from Presentation
+
+The framework must distinguish between:
+
+* what a Widget means
+* how a Widget is visually rendered
+
+### 12.3 Audit-Preserving Evolution
+
+Changes to requirements, decisions, and widget lineage must preserve historical traceability.
+
+### 12.4 Explicit Actor Attribution
+
+Interaction and decision artifacts must clearly distinguish:
+
+* human user
+* operator
+* reviewer
+* AI agent
+* automation process
+* anonymous or low-trust actor where applicable
+
+### 12.5 Governed AI Assistance
+
+AI-generated proposals must remain attributable and reviewable.
+
+### 12.6 Append-Oriented Event Storage
+
+Interaction events and key governance events should prefer append-oriented recording patterns.
+
+### 12.7 UI Framework Adaptability
+
+No long-term implementation should assume that one UI framework remains permanent.
+
+---
+
+## 13. Reference Technology Direction
+
+The initial reference implementation is intended to use:
+
+* **IHP** as server-centered application framework
+* **PostgreSQL** as canonical relational and event-linked datastore
+* IHP-supported realtime and server-side interaction capabilities for initial operational surfaces
+
+The reference implementation may later integrate:
+
+* richer client-side UI technologies
+* specialized visualization layers
+* external observability systems
+* message buses and workflow engines
+* AI inference and orchestration services
+
+The IHF specification remains broader than the first implementation.
+
+---
+
+# 14. Phased Implementation Plan
+
+## Phase 0 — Concept Foundation
+
+### Goal
+
+Create a coherent conceptual and structural baseline before coding the full platform core.
+
+### Objectives
+
+* define vocabulary
+* define artifact model
+* define hub alignment
+* define minimum traceability chain
+* define widget identity rules
+* define initial governance principles
+
+### Deliverables
+
+* IHF specification draft
+* canonical glossary
+* artifact inventory
+* initial domain model
+* naming and ID conventions
+* initial boundary diagram
+* first risk register
+
+### Exit Criteria
+
+* terminology is stable enough for repository creation
+* artifact set is sufficient for early implementation
+* phase 1 data model can be derived without conceptual ambiguity
+
+---
+
+## Phase 1 — Minimal Interaction Core
+
+### Goal
+
+Implement the minimum viable governed interaction substrate.
+
+### Scope
+
+* widget registry
+* widget envelope convention
+* interaction event capture
+* basic annotation support
+* hub and capability references
+* initial operator-facing dashboard
+* manual traceability from widget to annotation
+
+### Functional Capabilities
+
+* register a widget
+* render widget metadata into UI surfaces
+* capture basic interaction events
+* allow comments on a widget
+* list widget feedback by hub and capability
+* attribute feedback to actor and context
+* inspect interaction history for a widget
+
+### Data Artifacts Introduced
+
+* Widget
+* WidgetVersion
+* InteractionEvent
+* Annotation
+* Hub
+* CapabilityReference
+* ViewContext
+
+### Recommended UI
+
+* simple server-rendered IHP pages
+* minimal interactive enhancements
+* operational review screens before polished end-user surfaces
+
+### Exit Criteria
+
+* widgets can be addressed and commented reliably
+* interaction data is captured with context
+* hub-level inspection of interaction signals is possible
+
+---
+
+## Phase 2 — Structured Feedback and Triage
+
+### Goal
+
+Transform raw comments into structured, operable feedback.
+
+### Scope
+
+* annotation categories
+* annotation threads
+* severity or intensity markers
+* triage workflow
+* duplicate grouping
+* operator review views
+* basic requirement candidate creation
+
+### Functional Capabilities
+
+* categorize comments as friction, defect, wish, policy concern, trust issue, documentation gap, or other controlled classes
+* group similar observations
+* assign triage status
+* escalate issues into Requirement Candidates
+* track reviewer decisions
+
+### Data Artifacts Introduced
+
+* AnnotationThread
+* RequirementCandidate
+* TriageState
+* ReviewerAssignment
+
+### Exit Criteria
+
+* feedback volume can be triaged rather than merely stored
+* multiple related comments can converge into a structured candidate
+* reviewers can track status and ownership
+
+---
+
+## Phase 3 — Governance and Decision Linkage
+
+### Goal
+
+Make the framework governance-capable rather than feedback-capable only.
+
+### Scope
+
+* decision records
+* policy references
+* capability-linked decisions
+* implementation references
+* requirement promotion workflow
+* audit trail screens
+
+### Functional Capabilities
+
+* create formal Decision Records
+* link Requirement Candidates to decisions
+* record acceptance, rejection, deferral, split, merge, and reframe outcomes
+* connect decisions to implementation work items
+* maintain reviewable rationale
+
+### Data Artifacts Introduced
+
+* DecisionRecord
+* PolicyReference
+* Requirement
+* ImplementationChangeReference
+
+### Exit Criteria
+
+* the system can explain why a requirement was or was not acted upon
+* governance records are linked to observed interaction issues
+* decision history is inspectable by hub
+
+---
+
+## Phase 4 — Outcome Observation and Antifragility Loop
+
+### Goal
+
+Close the improvement loop by observing whether implemented changes helped.
+
+### Scope
+
+* deployment linkage
+* pre/post change comparison
+* outcome signals
+* regression detection
+* issue recurrence tracking
+* change effectiveness dashboards
+
+### Functional Capabilities
+
+* connect implementation changes to deployed versions
+* observe outcome signals after rollout
+* compare interaction behavior before and after change
+* detect repeated unresolved friction
+* score changes by observed effect
+
+### Data Artifacts Introduced
+
+* DeploymentRecord
+* OutcomeSignal
+* ChangeEvaluation
+
+### Exit Criteria
+
+* the platform can determine whether a change improved outcomes
+* recurrent friction becomes visible
+* the system supports evidence-based UI evolution
+
+---
+
+## Phase 5 — Agent-Assisted Distillation and Suggestion
+
+### Goal
+
+Introduce bounded AI support into the interaction-governance loop.
+
+### Scope
+
+* summarization of feedback clusters
+* AI-drafted requirement candidates
+* AI-assisted prioritization suggestions
+* policy conflict detection assistance
+* traceability-aware implementation proposal drafts
+
+### Functional Capabilities
+
+* generate summaries for feedback clusters
+* draft requirement descriptions
+* suggest likely duplicates
+* identify policy-sensitive issues
+* propose candidate implementation paths with traceability references
+
+### Governance Constraints
+
+* all AI outputs must be attributable
+* no silent requirement promotion
+* no autonomous final decisions
+* all AI-originated artifacts remain reviewable and reversible
+
+### Data Artifacts Introduced
+
+* AgentProposal
+* AgentReviewRecord
+* ConfidenceAnnotation
+
+### Exit Criteria
+
+* AI assistance reduces triage and synthesis burden
+* human reviewers remain in control
+* AI outputs are auditable and attributable
+
+---
+
+## Phase 6 — Cross-Framework UI Adaptation Layer
+
+### Goal
+
+Ensure semantic continuity while the UI stack diversifies.
+
+### Scope
+
+* widget protocol adapters
+* metadata emission standards
+* client-side SDKs or thin adapters
+* cross-framework annotation launcher
+* standardized interaction reporting interface
+
+### Functional Capabilities
+
+* integrate React or other client-side components without losing widget identity
+* maintain annotation compatibility across surfaces
+* preserve traceability across multiple UI technologies
+* support mixed rendering strategies in one platform
+
+### Artifacts Introduced
+
+* WidgetAdapterSpec
+* InteractionReportingContract
+* EnvelopeEmissionContract
+
+### Exit Criteria
+
+* new UI technologies can participate without bypassing the IHF core
+* widget identity remains stable across frontend evolution
+* annotations and interaction events remain compatible
+
+---
+
+## Phase 7 — Advanced Observability and Operational Integration
+
+### Goal
+
+Integrate interaction governance with broader operational intelligence.
+
+### Scope
+
+* hub health correlation
+* policy violation correlation
+* workflow bottleneck analysis
+* interaction pain heatmaps
+* queue and job linkage
+* cross-hub issue propagation analysis
+
+### Functional Capabilities
+
+* correlate interaction friction with operational failures
+* expose widget pain concentration by hub
+* detect systemic workflow bottlenecks
+* support operational review boards across Dev, Ops, Sec, Fin, and Governance Hubs
+
+### Exit Criteria
+
+* interaction data informs operational decision-making
+* hub leaders can inspect systemic friction patterns
+* the platform supports cross-domain learning
+
+---
+
+## Phase 8 — Federated Hub Maturity
+
+### Goal
+
+Support mature multi-hub deployment in an AI factory context.
+
+### Scope
+
+* delegated ownership
+* multi-team governance
+* inter-hub requirement routing
+* federated policy overlays
+* mature reporting and stewardship roles
+* long-term archival and lineage inspection
+
+### Functional Capabilities
+
+* route issues across hubs
+* distinguish local and global widget ownership
+* support federated review workflows
+* maintain lineage through deprecations and hub restructures
+
+### Exit Criteria
+
+* the framework supports organizational scale
+* ownership and governance remain clear across hub boundaries
+* long-term platform memory is preserved
+
+---
+
+# 15. Suggested Repository and Workstream Structure
+
+A practical initial structure could separate:
+
+* `ihf-spec`
+* `ihf-core`
+* `ihf-widget-registry`
+* `ihf-interaction-capture`
+* `ihf-annotations`
+* `ihf-governance`
+* `ihf-observation`
+* `ihf-agent-assist`
+* `ihf-adapters`
+* `ihf-ops`
+
+In a smaller start, these may begin in a single monorepo with clear internal module boundaries.
+
+---
+
+# 16. Priority Order for First Build
+
+If you want the strongest early leverage, implement in this order:
+
+1. Widget identity and envelope rules
+2. Widget registry
+3. Interaction event capture
+4. Annotation system
+5. Hub review dashboard
+6. Requirement candidate creation
+7. Decision linkage
+8. Outcome observation
+
+That order gives you a working feedback economy early.
+
+---
+
+# 17. Risks and Failure Modes
+
+## 17.1 Overcoupling to First UI Implementation
+
+Risk: the first rendering technology becomes the accidental permanent model.
+Mitigation: formalize envelope and reporting contracts early.
+
+## 17.2 Comment Noise Without Distillation
+
+Risk: large volumes of feedback create clutter.
+Mitigation: introduce structured categories and triage early.
+
+## 17.3 AI Proposal Pollution
+
+Risk: too many weak AI-generated candidates degrade trust.
+Mitigation: require attribution, confidence markers, and human review.
+
+## 17.4 Broken Traceability
+
+Risk: requirements and changes lose linkage over time.
+Mitigation: make traceability mandatory for promotion and rollout review.
+
+## 17.5 Semantic Drift of Widgets
+
+Risk: widget IDs stop reflecting actual continuity.
+Mitigation: define lineage and deprecation rules.
+
+---
+
+# 18. Success Criteria
+
+The Interaction Hub Framework is successful when:
+
+* meaningful UI units are stably addressable
+* users and operators can comment in context
+* feedback becomes structured requirements rather than dead text
+* decisions remain reviewable and linked to originating signals
+* implementations can be evaluated by observed outcomes
+* AI assistance improves throughput without obscuring accountability
+* UI technologies can evolve without destroying semantic continuity
+
+---
+
+# 19. Short Strategic Summary
+
+The Interaction Hub Framework should be built as a **governed interaction substrate**, not as a cosmetic UI layer and not as a rigid frontend monoculture.
+
+Its purpose is to make:
+
+* interaction observable
+* frustration actionable
+* hope capturable
+* change auditable
+* evolution evidence-based
+
+That is what gives it antifragile potential.
+
+
+xxx