plan

type Annotation struct {
	Section string    `json:"section,omitempty"`
	Kind    BadgeKind `json:"kind"`
	Type    BadgeType `json:"type"`
	Why     string    `json:"why"`
	// HumanWhy is the curated, decision-first phrasing used in the HTML render. It
	// drops agent-only provenance noise that Why carries for the --json/agent path
	// (commit SHAs, relative timestamps like "12h ago", workspace counts). The
	// renderer prefers HumanWhy when non-empty; --json keeps the raw Why intact.
	// Empty means "use Why" — most annotations need no separate human phrasing.
	HumanWhy  string   `json:"human_why,omitempty"`
	SourceURL string   `json:"source_url,omitempty"`
	Expert    string   `json:"expert,omitempty"`
	Files     []string `json:"files,omitempty"`
	// Date, Summary, RefKind carry the structured prior-art fields the renderer
	// composes into a crisp "person · date · summary" link. Environment-
	// independent (no URL), so they're safe to emit in `ox plan enrich --json`;
	// the web URL is built only at render time from the local project config.
	Date    string `json:"date,omitempty"`
	Summary string `json:"summary,omitempty"`
	RefKind string `json:"ref_kind,omitempty"` // session | plan | murmur
}

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 CraftReport struct {
	Emitted  int
	Realized int
	Gaps     []Finding
}

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
	Reviewer string         `json:"reviewer,omitempty"` // who left this mark (multi-user); stamped from the round on save
}

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
	// RemappedFrom is the item's original anchor when a plan update moved its
	// content and the save-time remap rebound it (see remap.go). Empty when the
	// mark still lives at its original address. Anchor always holds the CURRENT
	// address — the one `ox plan feedback resolve` acts on.
	RemappedFrom string `json:"remapped_from,omitempty"`
}

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 OpenFeedbackSummary struct {
	Slug      string `json:"slug"`
	Topic     string `json:"topic,omitempty"`
	Open      int    `json:"open"`                 // open, actionable items (approvals excluded)
	AgentType string `json:"agent_type,omitempty"` // authoring coworker type, if recorded
	Dir       string `json:"-"`                    // absolute plan dir (local only)
}

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 RemapEntry struct {
	From    string    `json:"from"`              // anchor that vanished from the render
	To      string    `json:"to"`                // anchor of the element it was rebound to
	Section string    `json:"section,omitempty"` // new element's section heading
	Label   string    `json:"label,omitempty"`   // new element's label
	Method  string    `json:"method"`            // label-exact | label-fuzzy
	Score   float64   `json:"score"`             // similarity that justified the rebind
	At      time.Time `json:"at"`
}

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
	// PriorArtURL resolves a prior-art source (its kind + ref/slug) to a SageOx
	// web URL, opened in a new tab from the enrichment panel. Nil-safe: when nil
	// or when it returns "", the prior-art entry renders as crisp text with no
	// link. This is the seam that keeps internal/plan config-agnostic — the
	// command layer builds the closure from the local project config, and
	// `ox plan enrich --json` (no config) never embeds an environment URL.
	PriorArtURL func(refKind, ref string) string
	// Artifact renders a strictly self-contained page with NO external resource
	// requests, suitable for publishing as a Claude Code Artifact (served under a
	// strict CSP that blocks all cross-origin script/style/font/img and all
	// fetch/XHR/WebSocket). In this mode the Google-Fonts <link> is dropped (the
	// font stacks fall back to system fonts), the SSE review layer is omitted, and
	// the Mermaid CDN <script> is replaced by the vendored library inlined in
	// place (only when the plan carries a diagram), so diagrams render at full
	// parity with zero network. The SageOx enrichment reference links are
	// preserved — top-level <a href> navigation is not CSP-blocked, so a published
	// artifact stays a hub back into the Ledger.
	Artifact bool
}

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"`
	// VizHints are deterministic per-section data-visualization suggestions
	// (which parameterized catalog pattern fits — risk-matrix, file-impact-map,
	// …), each renderable via `ox plan viz render <id> --data`. Empty when no
	// section matched a pattern's use: signal strongly enough.
	VizHints []VizHint `json:"viz_hints,omitempty"`
	// MockupSection is the heading of the section that changes a user-facing
	// surface (one the reader sees on screen), or "" when the plan changes nothing
	// visible. Detected deterministically at enrich (mockupCues, precision-gated
	// like the diagram hints) and surfaced in Guidance so every agent is told to
	// show a mockup pre-authoring; the render-time craft lint only checks it was
	// realized. Environment-independent, so it's safe in `ox plan enrich --json`.
	MockupSection string `json:"mockup_section,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 ReviewServerState struct {
	Port  int    `json:"port"`  // last port actually served on
	Token string `json:"token"` // review token the served pages carry
}

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 VizHint struct {
	Section   string `json:"section"`         // H2 heading the hint applies to
	PatternID string `json:"pattern_id"`      // catalog id, e.g. "risk-matrix" (renderable via `ox plan viz render`)
	Reason    string `json:"reason"`          // the trigger terms matched, in one clause
	Param     string `json:"param,omitempty"` // the pattern's `param:` JSON skeleton to fill and render
}

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
}