Add insert command

specs/005-add-insert-command/data-model.md

@@ -0,0 +1,62 @@
+# Data Model – Insert Command
+
+## Entity: InsertRequest
+- **Fields**
+  - `WorkingDir string` — Absolute path derived from CLI `--path` or current directory.
+  - `PositionToken string` — Raw user input (`^`, `$`, positive int, negative int) describing insertion point.
+  - `InsertText string` — Unicode string to insert.
+  - `IncludeDirs bool` — Mirrors `--include-dirs` scope flag.
+  - `Recursive bool` — Mirrors `--recursive`.
+  - `IncludeHidden bool` — True only when `--hidden` supplied.
+  - `ExtensionFilter []string` — Normalized tokens from `--extensions`.
+  - `DryRun bool` — Preview-only execution state.
+  - `AutoConfirm bool` — Captures `--yes` for non-interactive runs.
+  - `Timestamp time.Time` — Invocation timestamp for ledger correlation.
+- **Validation Rules**
+  - Reject empty `InsertText`, path separators, or control characters.
+  - Ensure `PositionToken` parses to a valid rune index relative to the stem (`^` = 0, `$` = len, positive 1-based, negative = offset from end).
+  - Confirm resulting filename is non-empty and does not change extension semantics.
+- **Relationships**
+  - Consumed by insert engine to plan operations.
+  - Serialized into ledger metadata with `InsertSummary`.
+
+## Entity: InsertSummary
+- **Fields**
+  - `TotalCandidates int` — Items inspected after scope filtering.
+  - `TotalChanged int` — Entries that will change after insertion.
+  - `NoChange int` — Entries already containing target string at position (if applicable).
+  - `Conflicts []Conflict` — Target collisions or invalid positions.
+  - `Warnings []string` — Validation notices (duplicates, trimmed tokens, skipped hidden items).
+  - `Entries []PreviewEntry` — Ordered original/proposed mappings with status.
+  - `LedgerMetadata map[string]any` — Snapshot persisted with ledger entry (position, text, scope flags).
+- **Validation Rules**
+  - Conflicts must be empty before apply.
+  - `TotalChanged + NoChange` equals count of entries with status `changed` or `no_change`.
+  - Entries sorted deterministically by original path.
+- **Relationships**
+  - Emitted to preview renderer and ledger writer.
+  - Input for undo verification.
+
+## Entity: Conflict
+- **Fields**
+  - `OriginalPath string`
+  - `ProposedPath string`
+  - `Reason string` — (`duplicate_target`, `invalid_position`, `existing_file`, etc.)
+- **Validation Rules**
+  - `ProposedPath` unique among planned operations.
+  - Reason restricted to known enum values for messaging.
+- **Relationships**
+  - Reported in preview output and used to block apply.
+
+## Entity: PreviewEntry
+- **Fields**
+  - `OriginalPath string`
+  - `ProposedPath string`
+  - `Status string` — `changed`, `no_change`, `skipped`.
+  - `InsertedText string` — Text segment inserted (for auditing).
+- **Validation Rules**
+  - `ProposedPath` equals `OriginalPath` when `Status == "no_change"`.
+  - `InsertedText` empty only for `no_change` or `skipped`.
+- **Relationships**
+  - Displayed in preview output.
+  - Persisted with ledger metadata for undo playback.