docs: polish structured learnings README for issue #4

internal/types/learnings.go

@@ -0,0 +1,79 @@
+package types
+
+import (
+	"time"
+
+	"github.com/google/uuid"
+)
+
+type EvidenceLevel string
+
+const (
+	EvidenceHypothesis EvidenceLevel = "hypothesis"
+	EvidenceObserved    EvidenceLevel = "observed"
+	EvidenceVerified   EvidenceLevel = "verified"
+)
+
+type LearningStatus string
+
+const (
+	StatusProvisional LearningStatus = "provisional"
+	StatusVerified    LearningStatus = "verified"
+	StatusDeprecated  LearningStatus = "deprecated"
+)
+
+type LearningPriority string
+
+const (
+	PriorityLow      LearningPriority = "low"
+	PriorityMedium   LearningPriority = "medium"
+	PriorityHigh     LearningPriority = "high"
+	PriorityCritical LearningPriority = "critical"
+)
+
+type Learning struct {
+	ID               uuid.UUID       `json:"id"`
+	Summary          string          `json:"summary"`
+	Details          string          `json:"details"`
+	Category         string          `json:"category"`
+	Area             string          `json:"area"`
+	Status           LearningStatus  `json:"status"`
+	Priority         LearningPriority `json:"priority"`
+	Confidence       EvidenceLevel   `json:"confidence"`
+	ActionRequired   bool            `json:"action_required"`
+	
+	// Provenance
+	SourceType       string          `json:"source_type"`
+	SourceRef        string          `json:"source_ref"`
+	
+	// Relations
+	ProjectID        *uuid.UUID     `json:"project_id,omitempty"`
+	RelatedThoughtID *uuid.UUID      `json:"related_thought_id,omitempty"`
+	RelatedSkillID   *uuid.UUID      `json:"related_skill_id,omitempty"`
+	
+	// Versioning/Review
+	ReviewedBy       *string         `json:"reviewed_by,omitempty"`
+	ReviewedAt       *time.Time      `json:"reviewed_at,omitempty"`
+	DuplicateOf      *uuid.UUID      `json:"duplicate_of,omitempty"`
+	Supersedes       *uuid.UUID      `json:"supersedes,omitempty"`
+	
+	Tags             []string        `json:"tags"`
+	CreatedAt        time.Time       `json:"created_at"`
+	UpdatedAt        time.Time       `json:"updated_at"`
+}
+
+type LearningFilter struct {
+	Limit       int
+	ProjectID   *uuid.UUID
+	Category    string
+	Area        string
+	Status      LearningStatus
+	Priority    LearningPriority
+	Tag         string
+	Query       string // Free-text search across summary/details
+}
+
+type LearningSearchResult struct {
+	Learning   Learning `json:"learning"`
+	Similarity float64  `json:"similarity"`
+}