plan

type Annotation struct {
	Section   string    `json:"section,omitempty"`
	Kind      BadgeKind `json:"kind"`
	Type      BadgeType `json:"type"`
	Why       string    `json:"why"`
	SourceURL string    `json:"source_url,omitempty"`
	Expert    string    `json:"expert,omitempty"`
	Files     []string  `json:"files,omitempty"`
}

type BadgeKind string

type BadgeType string

type BrandingFinding = Finding

type CollabSignals struct {
	UserPrompts     int `json:"user_prompts"`     // distinct human turns before the plan
	AgentQuestions  int `json:"agent_questions"`  // AskUserQuestion / clarifying tool calls
	ToolCalls       int `json:"tool_calls"`       // exploration-depth proxy
	DurationSeconds int `json:"duration_seconds"` // first user prompt → plan finalized
}

type ContextItem struct {
	Kind    string  `json:"kind"` // murmur|session|decision|adr|commit|discussion
	Title   string  `json:"title"`
	Ref     string  `json:"ref"`
	Snippet string  `json:"snippet,omitempty"`
	Score   float64 `json:"score"`
	Author  string  `json:"author,omitempty"`
	When    string  `json:"when,omitempty"`
}

type Detector interface {
	Name() string
	Detect(ctx context.Context, in Input, gitRoot string) ([]Annotation, error)
}

type DiagramHint struct {
	Section       string      `json:"section"`        // H2 heading the hint applies to
	SuggestedType DiagramKind `json:"suggested_type"` // the diagram form that fits
	Reason        string      `json:"reason"`         // what structure was detected, in one clause
}

type DiagramKind string

type FeedbackItem struct {
	Anchor  string         `json:"anchor"`            // stable content-hash id, e.g. "h3f9a1c2"
	Section string         `json:"section,omitempty"` // section heading the element sits under
	Label   string         `json:"label"`             // short text of the element
	Status  FeedbackStatus `json:"status"`            // approve | request-change | flag | comment
	Note    string         `json:"note,omitempty"`    // the reviewer's comment
}

type FeedbackSet struct {
	Slug      string         `json:"slug"`
	Reviewer  string         `json:"reviewer,omitempty"`
	CreatedAt time.Time      `json:"created_at"`
	Items     []FeedbackItem `json:"items"`
}

type FeedbackStatus string

type Finding struct {
	Rule    string // stable id, e.g. "branding.footer-credit" / "mermaid.arrow-in-label"
	Message string // human-readable, actionable
}

type Input struct {
	Path     string
	Raw      string
	Sections []Section
}

type MergedItem struct {
	FeedbackItem
	RaisedAt   time.Time
	Resolution *Resolution
	Open       bool
}

type Meta struct {
	// SchemaVersion stamps the meta.json shape (set to SchemaVersion on write)
	// so a future reader can detect and migrate an older layout.
	SchemaVersion  string    `json:"schema_version,omitempty"`
	Topic          string    `json:"topic"`
	Slug           string    `json:"slug"`
	Authors        []string  `json:"authors,omitempty"`
	CreatedAt      time.Time `json:"created_at"`
	SourcePlanPath string    `json:"source_plan_path,omitempty"`

	// Status is the plan's lifecycle. Missing == "draft" for legacy plans.
	Status PlanStatus `json:"status,omitempty"`
	// Provenance links the plan to its producing session/agent/repo (forward).
	Provenance *Provenance `json:"provenance,omitempty"`
	// Collaboration holds the deterministic collaboration-effort counts.
	Collaboration *CollabSignals `json:"collaboration,omitempty"`
}

type PlanInfo struct {
	Slug      string
	Topic     string
	Dir       string
	CreatedAt time.Time
	Authors   []string
	HasHTML   bool
}

type PlanStatus string

type Provenance struct {
	// Join keys (may dangle if the session was aborted / never uploaded).
	//
	// Two-phase population, because the canonical ses_ SessionID is minted
	// fresh at session-STOP and is NOT knowable mid-recording:
	//   - SessionName is the durable identifier available at plan-save time
	//     (the recording's folder name, what `ox session view <name>` resolves).
	//     It is the primary join key and is always set when a recording is live.
	//   - SessionID (ses_<UUIDv7>) is BACKFILLED at session-stop, in the same
	//     reconciliation that sets SessionOutcome=stopped — we have the real id
	//     and the produced-plan slugs in hand there. Empty for aborted sessions
	//     (no stop) and for plans saved outside a recording.
	SessionName string `json:"session_name,omitempty"`
	SessionID   string `json:"session_id,omitempty"` // ses_<UUIDv7>, backfilled at stop
	AgentID     string `json:"agent_id,omitempty"`   // Ox#### stable agent instance
	RepoID      string `json:"repo_id,omitempty"`

	// Denormalized snapshot — renders without the session present.
	AgentType  string `json:"agent_type,omitempty"` // claude-code, codex, ...
	Model      string `json:"model,omitempty"`
	AuthorName string `json:"author_name,omitempty"` // privacy-safe display name at save time

	// SessionOutcome is RECONCILED SYSTEM STATE, not authored provenance:
	// "" (unknown) | "active" | "stopped" | "aborted". Written only by
	// session-stop / `ox doctor` through MutatePlanMeta, never by Save.
	SessionOutcome string `json:"session_outcome,omitempty"`
}

type RenderOptions struct {
	Slug string
	// Review is the merged review state (rounds + resolutions) for this plan, so
	// the render can show each item's open/addressed state inline and in a
	// summary. Empty for a plan with no review yet.
	Review []MergedItem
	// ReviewEndpoint + ReviewToken are set ONLY when the page is served by the
	// ephemeral `ox plan review` server: the page POSTs marks to the endpoint
	// with the token. Empty for a static file:// render (clipboard fallback).
	ReviewEndpoint string
	ReviewToken    string
}

type Resolution struct {
	Anchor string          `json:"anchor"`           // the item it resolves
	State  ResolutionState `json:"state"`            // addressed | wontfix | verified
	Commit string          `json:"commit,omitempty"` // commit SHA that made the change
	Note   string          `json:"note,omitempty"`   // what the agent did / why wontfix
	At     time.Time       `json:"at"`
}

type ResolutionState string

type Result struct {
	// SchemaVersion stamps the serialized annotations.json shape (set to
	// SchemaVersion on write) so a future reader can detect an older layout.
	SchemaVersion string        `json:"schema_version,omitempty"`
	Annotations   []Annotation  `json:"annotations"`
	Context       []ContextItem `json:"context"`
	Signals       SignalSummary `json:"signals"`
	// DiagramHints are deterministic per-section diagram suggestions (which
	// Mermaid/timeline form fits the structure ox detected). Empty when no
	// section had strong enough structure to suggest one.
	DiagramHints []DiagramHint `json:"diagram_hints,omitempty"`
	// Guidance is a concise, cross-agent authoring contract for rendering a
	// fantastic HTML plan (decision-first, ten-minute reader, diagrams over
	// prose). It folds in the DiagramHints so the agent gets plan-specific
	// direction, not a generic spec. Empty for a trivial/empty plan.
	Guidance string `json:"guidance,omitempty"`
}

type Retriever interface {
	Name() string
	Retrieve(ctx context.Context, in Input, gitRoot string) ([]ContextItem, error)
}

type Section struct {
	Heading string
	Body    string
	Files   []string
}

type SignalSummary struct {
	Collisions   int  `json:"collisions"`
	PriorArt     int  `json:"prior_art"`
	ExpertRoutes int  `json:"expert_routes"`
	Material     bool `json:"material"`
	Files        int  `json:"files"`
	Steps        int  `json:"steps"`
	NonTrivial   bool `json:"non_trivial"`
}

type VizPattern struct {
	ID    string `json:"id"`              // stable slug, e.g. "sparkline"
	Use   string `json:"use"`             // when to reach for it
	Why   string `json:"why"`             // the cognitive payoff
	Param string `json:"param,omitempty"` // data-shape hint when `ox plan viz render <id> --data` is supported
	Body  string `json:"body"`            // copy-paste snippet(s) + any notes
}