@hanna84/mcp-writing 3.28.0 → 3.29.1

package/CHANGELOG.md

@@ -4,9 +4,23 @@ All notable changes to this project will be documented in this file. Dates are d
 
 Generated by [`auto-changelog`](https://github.com/CookPete/auto-changelog).
 
+#### [v3.29.1](https://github.com/hannasdev/mcp-writing/compare/v3.29.0...v3.29.1)
+
+- docs: close Human Input Forgiveness initiative [`#240`](https://github.com/hannasdev/mcp-writing/pull/240)
+
+#### [v3.29.0](https://github.com/hannasdev/mcp-writing/compare/v3.28.0...v3.29.0)
+
+> 7 June 2026
+
+- feat: resolve scene vocabulary variants [`#239`](https://github.com/hannasdev/mcp-writing/pull/239)
+- Release 3.29.0 [`bb81824`](https://github.com/hannasdev/mcp-writing/commit/bb81824fcb04640b3e62fae2cee6bd39bcd8af14)
+
 #### [v3.28.0](https://github.com/hannasdev/mcp-writing/compare/v3.27.0...v3.28.0)
 
+> 7 June 2026
+
 - feat: make restore plans easier to scan [`#238`](https://github.com/hannasdev/mcp-writing/pull/238)
+- Release 3.28.0 [`f0add03`](https://github.com/hannasdev/mcp-writing/commit/f0add03b915962d72dcac5c745b9000d50d6a819)
 
 #### [v3.27.0](https://github.com/hannasdev/mcp-writing/compare/v3.26.0...v3.27.0)
 

package/README.md

@@ -28,7 +28,7 @@ Instead of feeding an entire manuscript to an AI and hoping it fits in the conte
 
 **Current status:**
 - **Core platform complete:** Metadata-first analysis, SQLite-canonical structural and relationship metadata, compatibility sidecar maintenance, AI-assisted prose editing with confirmation + git history, review bundles, and Scrivener Direct extraction are all implemented.
-- **Recently completed:** Relationship Metadata Boundary closed the sidecar-first scene relationship mutation path, added SQLite-first paired and one-sided evidence workflows, and preserved legacy sidecar/frontmatter compatibility for sync and import.
+- **Recently completed:** Human Input Forgiveness made selected request-boundary inputs more forgiving, clarified keyword metadata search boundaries, and recorded temp-fixture replay validation while preserving stable canonical IDs.
 - **Active development:** No initiative is currently selected.
 - **Deferred backlog:** OpenClaw integration, client-agnostic setup, divisions, and embeddings search.
 - **Ideas and open questions:** tracked separately so future exploration does not distort the active roadmap.
@@ -122,6 +122,16 @@ const items = parsed.results ?? [];
 const totalCount = parsed.total_count ?? items.length;
 ```
 
+## Canonical IDs and forgiving inputs
+
+Stable IDs remain the canonical identity for projects, chapters, scenes, characters, places, and relationship writes. When you already know the ID, pass it exactly.
+
+Some request-boundary fields now accept unambiguous human-shaped inputs, such as scene titles, character names, place names, or case variants. Successful tools still write and return canonical IDs, with `resolved_from` details when the input was resolved from a non-canonical value. Ambiguous matches, near matches, or suggested-only values fail or return advisory suggestions without mutating canonical state.
+
+Tags and Save the Cat beats remain freeform editorial vocabulary. `find_scenes` can match existing tag and beat casing variants, and metadata updates can suggest nearby existing vocabulary, but supplied tag and beat text is preserved unless you intentionally change it.
+
+`search_metadata` is keyword/FTS metadata search over indexed titles, loglines, tags, characters, places, and versions. It is not semantic search and does not search prose text; use `get_scene_prose` after metadata search or structured filters identify likely scenes. Semantic/prose search remains deferred to the Embedding-Based Search backlog.
+
 ## Usage scenarios
 
 ### 1) Continuity pass before sending chapters to beta readers
@@ -129,7 +139,7 @@ const totalCount = parsed.total_count ?? items.length;
 Goal: catch inconsistencies before sharing pages.
 
 1. Run `sync` after your latest writing session.
-2. Ask `find_scenes` for scenes involving a specific character or tag (for example, all scenes tagged `injury` or `promise`).
+2. Ask `find_scenes` for scenes involving a specific character or tag (for example, all scenes tagged `injury` or `promise`). Canonical IDs remain preferred, but character/POV filters can resolve unambiguous project-scoped character names, tag and beat filters can suggest near matches, and `chapter_id` accepts exact IDs or unambiguous case variants.
 3. Use `get_arc` to review that character's ordered progression across the manuscript.
 4. Load only the suspect scenes with `get_scene_prose`.
 5. Attach follow-up notes with `flag_scene` where continuity needs a fix.
@@ -152,7 +162,7 @@ Outcome: subplot structure stays visible and auditable, which reduces dropped th
 Goal: keep indexes accurate without manually re-tagging everything.
 
 1. After rewriting scenes, call `enrich_scene` to re-derive lightweight metadata from current prose.
-2. Use `update_scene_metadata` for intentional editorial fields (for example, beat, POV, status, and tags). It rejects scene `characters` and `places`; use `connect_character_place_evidence` when a scene proves paired sheet-backed character/place evidence, `connect_scene_character_evidence` for character-only evidence, and `connect_scene_place_evidence` for place-only evidence. Those relationship evidence tools prefer canonical IDs but also accept unambiguous scene titles, character names, place names, and case variants; ambiguous or suggested-only matches fail without mutating state. Use `audit_relationship_metadata` for retained sidecar/frontmatter relationship fields. Use `list_chapters` plus `assign_scene_to_chapter` or `move_scene` for chapter placement and ordering.
+2. Use `update_scene_metadata` for intentional editorial fields (for example, beat, POV, status, and tags). Tags and beats remain freeform; the tool preserves supplied text while returning suggestions when a value resembles existing vocabulary. It rejects scene `characters` and `places`; use `connect_character_place_evidence` when a scene proves paired sheet-backed character/place evidence, `connect_scene_character_evidence` for character-only evidence, and `connect_scene_place_evidence` for place-only evidence. Those relationship evidence tools prefer canonical IDs but also accept unambiguous scene titles, character names, place names, and case variants; ambiguous or suggested-only matches fail without mutating state. Use `audit_relationship_metadata` for retained sidecar/frontmatter relationship fields. Use `list_chapters` plus `assign_scene_to_chapter` or `move_scene` for chapter placement and ordering.
 3. Use `search_metadata` for keyword/FTS metadata searches across indexed titles, loglines, tags, characters, places, and versions, and use `find_scenes` to verify scenes are discoverable under structured filters. After identifying likely scenes, use `get_scene_prose` for prose context.
 
 Outcome: your AI assistant can reliably find the right scenes without drifting from the manuscript.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hanna84/mcp-writing",
-  "version": "3.28.0",
+  "version": "3.29.1",
   "description": "MCP service for AI-assisted reasoning and editing on long-form fiction projects",
   "homepage": "https://hannasdev.github.io/mcp-writing/",
   "type": "module",

package/src/core/canonical-target-resolution.js

@@ -1,3 +1,5 @@
+import { isNearMatch, normalizeMatchValue } from "./match-utils.js";
+
 const DEFAULT_CANDIDATE_LIMIT = 5;
 const HARD_CANDIDATE_LIMIT = 10;
 
@@ -9,10 +11,6 @@ const MATCH_GROUP_ORDER = new Map([
   ["near_match_suggestion", 3],
 ]);
 
-function normalizeValue(value) {
-  return String(value ?? "").trim().toLowerCase();
-}
-
 function clampCandidateLimit(candidateLimit) {
   if (!Number.isInteger(candidateLimit) || candidateLimit <= 0) {
     return DEFAULT_CANDIDATE_LIMIT;
@@ -24,50 +22,12 @@ function getProjectUniverseId(db, projectId) {
   return db.prepare(`SELECT universe_id FROM projects WHERE project_id = ?`).get(projectId)?.universe_id ?? null;
 }
 
-function levenshteinDistance(left, right) {
-  if (left === right) return 0;
-  if (left.length === 0) return right.length;
-  if (right.length === 0) return left.length;
-
-  const previous = Array.from({ length: right.length + 1 }, (_, index) => index);
-  const current = Array.from({ length: right.length + 1 }, () => 0);
-
-  for (let leftIndex = 1; leftIndex <= left.length; leftIndex += 1) {
-    current[0] = leftIndex;
-    for (let rightIndex = 1; rightIndex <= right.length; rightIndex += 1) {
-      const cost = left[leftIndex - 1] === right[rightIndex - 1] ? 0 : 1;
-      current[rightIndex] = Math.min(
-        current[rightIndex - 1] + 1,
-        previous[rightIndex] + 1,
-        previous[rightIndex - 1] + cost
-      );
-    }
-    for (let index = 0; index < previous.length; index += 1) {
-      previous[index] = current[index];
-    }
-  }
-
-  return previous[right.length];
-}
-
-function isNearMatch(input, value) {
-  const normalizedInput = normalizeValue(input);
-  const normalizedValue = normalizeValue(value);
-  if (!normalizedInput || !normalizedValue) return false;
-  if (normalizedInput.length < 3 || normalizedValue.length < 3) return false;
-  if (normalizedValue.includes(normalizedInput) || normalizedInput.includes(normalizedValue)) return true;
-
-  const distance = levenshteinDistance(normalizedInput, normalizedValue);
-  const threshold = Math.max(1, Math.floor(Math.max(normalizedInput.length, normalizedValue.length) / 4));
-  return distance <= threshold;
-}
-
 function sortCandidates(candidates) {
   return [...candidates].sort((left, right) => {
     const groupDelta = (MATCH_GROUP_ORDER.get(left.match_type) ?? 99) - (MATCH_GROUP_ORDER.get(right.match_type) ?? 99);
     if (groupDelta !== 0) return groupDelta;
 
-    const labelDelta = normalizeValue(left.label).localeCompare(normalizeValue(right.label));
+    const labelDelta = normalizeMatchValue(left.label).localeCompare(normalizeMatchValue(right.label));
     if (labelDelta !== 0) return labelDelta;
 
     return left.id.localeCompare(right.id);
@@ -210,7 +170,7 @@ function resolveFromRows({
   candidateLimit,
   formatCandidate,
 }) {
-  const normalizedInput = normalizeValue(input);
+  const normalizedInput = normalizeMatchValue(input);
   if (!normalizedInput) {
     return buildResolutionFailure({
       targetKind,
@@ -236,7 +196,7 @@ function resolveFromRows({
     });
   }
 
-  const caseInsensitiveIdRows = rows.filter(row => normalizeValue(row[idField]) === normalizedInput);
+  const caseInsensitiveIdRows = rows.filter(row => normalizeMatchValue(row[idField]) === normalizedInput);
   if (caseInsensitiveIdRows.length === 1) {
     const candidate = formatCandidate(caseInsensitiveIdRows[0], { matchedField: idField, matchType: "case_insensitive_id" });
     return buildSuccess({
@@ -263,7 +223,7 @@ function resolveFromRows({
     });
   }
 
-  const caseInsensitiveNameRows = rows.filter(row => normalizeValue(row[nameField]) === normalizedInput);
+  const caseInsensitiveNameRows = rows.filter(row => normalizeMatchValue(row[nameField]) === normalizedInput);
   if (caseInsensitiveNameRows.length === 1) {
     const candidate = formatCandidate(caseInsensitiveNameRows[0], { matchedField: nameField, matchType: nameMatchType });
     return buildSuccess({

package/src/core/match-utils.js

@@ -0,0 +1,41 @@
+export function normalizeMatchValue(value) {
+  return String(value ?? "").trim().toLowerCase();
+}
+
+export function levenshteinDistance(left, right) {
+  if (left === right) return 0;
+  if (left.length === 0) return right.length;
+  if (right.length === 0) return left.length;
+
+  const previous = Array.from({ length: right.length + 1 }, (_, index) => index);
+  const current = Array.from({ length: right.length + 1 }, () => 0);
+
+  for (let leftIndex = 1; leftIndex <= left.length; leftIndex += 1) {
+    current[0] = leftIndex;
+    for (let rightIndex = 1; rightIndex <= right.length; rightIndex += 1) {
+      const cost = left[leftIndex - 1] === right[rightIndex - 1] ? 0 : 1;
+      current[rightIndex] = Math.min(
+        current[rightIndex - 1] + 1,
+        previous[rightIndex] + 1,
+        previous[rightIndex - 1] + cost
+      );
+    }
+    for (let index = 0; index < previous.length; index += 1) {
+      previous[index] = current[index];
+    }
+  }
+
+  return previous[right.length];
+}
+
+export function isNearMatch(input, value) {
+  const normalizedInput = normalizeMatchValue(input);
+  const normalizedValue = normalizeMatchValue(value);
+  if (!normalizedInput || !normalizedValue) return false;
+  if (normalizedInput.length < 3 || normalizedValue.length < 3) return false;
+  if (normalizedValue.includes(normalizedInput) || normalizedInput.includes(normalizedValue)) return true;
+
+  const distance = levenshteinDistance(normalizedInput, normalizedValue);
+  const threshold = Math.max(1, Math.floor(Math.max(normalizedInput.length, normalizedValue.length) / 4));
+  return distance <= threshold;
+}

package/src/core/vocabulary-resolution.js

@@ -0,0 +1,269 @@
+import { isNearMatch, normalizeMatchValue } from "./match-utils.js";
+
+const DEFAULT_VOCABULARY_CANDIDATE_LIMIT = 5;
+const HARD_VOCABULARY_CANDIDATE_LIMIT = 10;
+
+function normalizeVocabularyValue(value) {
+  return normalizeMatchValue(value);
+}
+
+function clampCandidateLimit(candidateLimit) {
+  if (!Number.isInteger(candidateLimit) || candidateLimit <= 0) {
+    return DEFAULT_VOCABULARY_CANDIDATE_LIMIT;
+  }
+  return Math.min(candidateLimit, HARD_VOCABULARY_CANDIDATE_LIMIT);
+}
+
+function cleanVocabularyValues(values) {
+  const seen = new Set();
+  const cleaned = [];
+  for (const value of Array.isArray(values) ? values : []) {
+    if (typeof value !== "string") continue;
+    const normalized = normalizeVocabularyValue(value);
+    if (!normalized) continue;
+    if (seen.has(value)) continue;
+    seen.add(value);
+    cleaned.push(value);
+  }
+  return cleaned.sort((left, right) => (
+    normalizeVocabularyValue(left).localeCompare(normalizeVocabularyValue(right)) || left.localeCompare(right)
+  ));
+}
+
+function formatVocabularyCandidate({ targetKind, value, matchedField, matchType }) {
+  return {
+    target_kind: targetKind,
+    id: value,
+    value,
+    label: value,
+    matched_field: matchedField,
+    match_type: matchType,
+  };
+}
+
+function capVocabularyCandidates(candidates, candidateLimit) {
+  return candidates
+    .sort((left, right) => (
+      normalizeVocabularyValue(left.label).localeCompare(normalizeVocabularyValue(right.label)) ||
+      left.id.localeCompare(right.id)
+    ))
+    .slice(0, clampCandidateLimit(candidateLimit));
+}
+
+export function resolveVocabularyValue({
+  input,
+  values,
+  targetKind,
+  matchedField = "value",
+  candidateLimit = DEFAULT_VOCABULARY_CANDIDATE_LIMIT,
+} = {}) {
+  const normalizedInput = normalizeVocabularyValue(input);
+  const vocabularyValues = cleanVocabularyValues(values);
+  if (!normalizedInput) {
+    return {
+      ok: false,
+      input,
+      target_kind: targetKind,
+      candidate_matches: [],
+    };
+  }
+
+  const caseInsensitiveMatches = vocabularyValues.filter(value => normalizeVocabularyValue(value) === normalizedInput);
+  if (caseInsensitiveMatches.length === 1) {
+    const canonicalValue = caseInsensitiveMatches[0];
+    return {
+      ok: true,
+      input,
+      target_kind: targetKind,
+      value: canonicalValue,
+      canonical: canonicalValue === input,
+      ...(canonicalValue === input ? {} : {
+        resolved_from: {
+          input,
+          matched_field: matchedField,
+          match_type: "case_insensitive_value",
+          value: canonicalValue,
+        },
+      }),
+    };
+  }
+  if (caseInsensitiveMatches.length > 1) {
+    return {
+      ok: true,
+      input,
+      target_kind: targetKind,
+      value: input,
+      canonical: false,
+      case_variants: caseInsensitiveMatches.map(value => formatVocabularyCandidate({
+        targetKind,
+        value,
+        matchedField,
+        matchType: "case_insensitive_value",
+      })),
+    };
+  }
+
+  const suggestions = vocabularyValues
+    .filter(value => isNearMatch(input, value))
+    .map(value => formatVocabularyCandidate({
+      targetKind,
+      value,
+      matchedField,
+      matchType: "near_match_suggestion",
+    }));
+
+  return {
+    ok: false,
+    input,
+    target_kind: targetKind,
+    candidate_matches: capVocabularyCandidates(suggestions, candidateLimit),
+  };
+}
+
+export function selectSceneTagVocabulary(db, { projectId } = {}) {
+  const rows = projectId
+    ? db.prepare(`
+      SELECT DISTINCT tag
+      FROM scene_tags
+      WHERE project_id = ? AND tag IS NOT NULL AND tag != ''
+      ORDER BY tag COLLATE NOCASE, tag
+    `).all(projectId)
+    : db.prepare(`
+      SELECT DISTINCT tag
+      FROM scene_tags
+      WHERE tag IS NOT NULL AND tag != ''
+      ORDER BY tag COLLATE NOCASE, tag
+    `).all();
+  return rows.map(row => row.tag);
+}
+
+export function selectSceneBeatVocabulary(db, { projectId } = {}) {
+  const rows = projectId
+    ? db.prepare(`
+      SELECT DISTINCT save_the_cat_beat AS beat
+      FROM scenes
+      WHERE project_id = ? AND save_the_cat_beat IS NOT NULL AND save_the_cat_beat != ''
+      ORDER BY save_the_cat_beat COLLATE NOCASE, save_the_cat_beat
+    `).all(projectId)
+    : db.prepare(`
+      SELECT DISTINCT save_the_cat_beat AS beat
+      FROM scenes
+      WHERE save_the_cat_beat IS NOT NULL AND save_the_cat_beat != ''
+      ORDER BY save_the_cat_beat COLLATE NOCASE, save_the_cat_beat
+    `).all();
+  return rows.map(row => row.beat);
+}
+
+export function selectSceneTagCaseVariants(db, { projectId, input } = {}) {
+  if (!input) return [];
+  const rows = projectId
+    ? db.prepare(`
+      SELECT DISTINCT tag
+      FROM scene_tags
+      WHERE project_id = ? AND tag IS NOT NULL AND tag != ''
+        AND lower(tag) = lower(?)
+      ORDER BY tag COLLATE NOCASE, tag
+    `).all(projectId, input)
+    : db.prepare(`
+      SELECT DISTINCT tag
+      FROM scene_tags
+      WHERE tag IS NOT NULL AND tag != ''
+        AND lower(tag) = lower(?)
+      ORDER BY tag COLLATE NOCASE, tag
+    `).all(input);
+  return rows.map(row => row.tag);
+}
+
+export function selectSceneBeatCaseVariants(db, { projectId, input } = {}) {
+  if (!input) return [];
+  const rows = projectId
+    ? db.prepare(`
+      SELECT DISTINCT save_the_cat_beat AS beat
+      FROM scenes
+      WHERE project_id = ? AND save_the_cat_beat IS NOT NULL AND save_the_cat_beat != ''
+        AND lower(save_the_cat_beat) = lower(?)
+      ORDER BY save_the_cat_beat COLLATE NOCASE, save_the_cat_beat
+    `).all(projectId, input)
+    : db.prepare(`
+      SELECT DISTINCT save_the_cat_beat AS beat
+      FROM scenes
+      WHERE save_the_cat_beat IS NOT NULL AND save_the_cat_beat != ''
+        AND lower(save_the_cat_beat) = lower(?)
+      ORDER BY save_the_cat_beat COLLATE NOCASE, save_the_cat_beat
+    `).all(input);
+  return rows.map(row => row.beat);
+}
+
+export function buildVocabularyNoResultsDetails({
+  filters,
+  resolvedFilters,
+  suggestions = [],
+  nextStep = "Broaden filters, choose a candidate value, or call search_metadata with exact metadata keywords.",
+} = {}) {
+  return {
+    lookup_kind: "scene_metadata_filters",
+    filters,
+    ...(resolvedFilters ? { resolved_filters: resolvedFilters } : {}),
+    candidate_matches: suggestions.flatMap(suggestion => suggestion.candidate_matches ?? []),
+    filter_suggestions: suggestions,
+    next_step: nextStep,
+  };
+}
+
+export function buildFreeformFieldSuggestions({
+  fields,
+  vocabulary,
+} = {}) {
+  const suggestions = {};
+  if (Array.isArray(fields?.tags) && Array.isArray(vocabulary?.tags)) {
+    const tagSuggestions = fields.tags
+      .map(tag => resolveVocabularyValue({
+        input: tag,
+        values: vocabulary.tags,
+        targetKind: "tag",
+        matchedField: "tag",
+      }))
+      .filter(result => result.ok && result.resolved_from)
+      .map(result => ({
+        field: "tags",
+        input: result.input,
+        existing_value: result.value,
+        match_type: result.resolved_from.match_type,
+        note: "Existing tag differs only by case; supplied casing was preserved because tags remain freeform metadata.",
+      }));
+    if (tagSuggestions.length > 0) suggestions.tags = tagSuggestions;
+  }
+
+  if (typeof fields?.save_the_cat_beat === "string" && Array.isArray(vocabulary?.beats)) {
+    const beatSuggestion = resolveVocabularyValue({
+      input: fields.save_the_cat_beat,
+      values: vocabulary.beats,
+      targetKind: "beat",
+      matchedField: "save_the_cat_beat",
+    });
+    if (beatSuggestion.ok && beatSuggestion.resolved_from) {
+      suggestions.save_the_cat_beat = [{
+        field: "save_the_cat_beat",
+        input: beatSuggestion.input,
+        existing_value: beatSuggestion.value,
+        match_type: beatSuggestion.resolved_from.match_type,
+        note: "Existing beat differs only by case; supplied value was preserved because Save the Cat beat remains freeform metadata.",
+      }];
+    } else if (!beatSuggestion.ok && beatSuggestion.candidate_matches.length > 0) {
+      suggestions.save_the_cat_beat = beatSuggestion.candidate_matches.map(candidate => ({
+        field: "save_the_cat_beat",
+        input: fields.save_the_cat_beat,
+        suggested_value: candidate.value,
+        match_type: candidate.match_type,
+        note: "Beat remains freeform; choose an existing value only if it matches author intent.",
+      }));
+    }
+  }
+
+  return Object.keys(suggestions).length > 0 ? suggestions : undefined;
+}
+
+export const VOCABULARY_CANDIDATE_LIMITS = {
+  default: DEFAULT_VOCABULARY_CANDIDATE_LIMIT,
+  hard: HARD_VOCABULARY_CANDIDATE_LIMIT,
+};

package/src/tools/metadata.js

@@ -10,6 +10,11 @@ import {
   resolvePlaceTargetForProject,
   resolveSceneTarget,
 } from "../core/canonical-target-resolution.js";
+import {
+  buildFreeformFieldSuggestions,
+  selectSceneBeatVocabulary,
+  selectSceneTagVocabulary,
+} from "../core/vocabulary-resolution.js";
 import {
   FILESYSTEM_ARTIFACT_CLASSES,
   assertRegularFileReadTarget,
@@ -2636,7 +2641,7 @@ export function registerMetadataTools(s, {
   // ---- update_scene_metadata -----------------------------------------------
   s.tool(
     "update_scene_metadata",
-    "Update one or more non-structural, non-relationship metadata fields for a scene. Writes only supplied allowed fields to the .meta.yaml sidecar and preserves existing structural compatibility fields; it never modifies prose, mirrors path-derived structure, or changes scene character/place relationship authority. Structural fields (part, chapter, chapter_id, chapter_title, timeline_position) are rejected here; use list_chapters plus assign_scene_to_chapter, move_scene, rename_chapter, or reorder_chapter for structure changes. Relationship fields (characters, places) are rejected here; use discovery workflows plus connect_character_place_evidence when evidence is paired, connect_scene_character_evidence for character-only evidence, connect_scene_place_evidence for place-only evidence, and audit_relationship_metadata for legacy sidecar/frontmatter relationship review. Allowed changes are immediately reflected in the index. Only available when the sync dir is writable.",
+    "Update one or more non-structural, non-relationship metadata fields for a scene. Writes only supplied allowed fields to the .meta.yaml sidecar and preserves existing structural compatibility fields; it never modifies prose, mirrors path-derived structure, or changes scene character/place relationship authority. Structural fields (part, chapter, chapter_id, chapter_title, timeline_position) are rejected here; use list_chapters plus assign_scene_to_chapter, move_scene, rename_chapter, or reorder_chapter for structure changes. Relationship fields (characters, places) are rejected here; use discovery workflows plus connect_character_place_evidence when evidence is paired, connect_scene_character_evidence for character-only evidence, connect_scene_place_evidence for place-only evidence, and audit_relationship_metadata for legacy sidecar/frontmatter relationship review. Tags and Save the Cat beat remain freeform; responses may include field_suggestions when supplied values resemble existing vocabulary, but supplied casing/text is preserved. Allowed changes are immediately reflected in the index. Only available when the sync dir is writable.",
     {
       scene_id:   z.string().describe("The scene_id to update (e.g. 'sc-011-sebastian')."),
       project_id: z.string().describe("Project the scene belongs to (e.g. 'the-lamb')."),
@@ -2644,7 +2649,7 @@ export function registerMetadataTools(s, {
         title:             z.string().optional(),
         logline:           z.string().optional(),
         status:            z.string().optional().describe("Workflow status (e.g. 'draft', 'revision', 'complete'). Free text — no fixed vocabulary."),
-        save_the_cat_beat: z.string().optional(),
+        save_the_cat_beat: z.string().optional().describe("Freeform Save the Cat beat. Suggestions may be returned when the value resembles existing indexed beats, but the supplied value is preserved."),
         pov:               z.string().optional(),
         part:              z.number().int().optional().describe("Rejected by update_scene_metadata. Structural placement must use explicit structure workflows."),
         chapter:           z.number().int().optional().describe("Rejected by update_scene_metadata. Use assign_scene_to_chapter or move_scene with canonical chapter_id."),
@@ -2652,7 +2657,7 @@ export function registerMetadataTools(s, {
         chapter_title:     z.string().nullable().optional().describe("Rejected by update_scene_metadata. Use rename_chapter for canonical chapter title changes."),
         timeline_position: z.number().int().optional().describe("Rejected by update_scene_metadata. Use move_scene for ordering changes."),
         story_time:        z.string().optional(),
-        tags:              z.array(z.string()).optional(),
+        tags:              z.array(z.string()).optional().describe("Freeform scene tags. Suggestions may be returned when supplied values differ only by case from existing tags, but supplied casing is preserved."),
         characters:        z.array(z.string()).optional().describe("Rejected by update_scene_metadata. Use find_scenes, list_characters, list_places, connect_character_place_evidence when evidence is paired, connect_scene_character_evidence for character-only evidence, and audit_relationship_metadata for compatibility review."),
         places:            z.array(z.string()).optional().describe("Rejected by update_scene_metadata. Use find_scenes, list_characters, list_places, connect_character_place_evidence when evidence is paired, connect_scene_place_evidence for place-only evidence, and audit_relationship_metadata for compatibility review."),
       }).describe("Fields to update. Only supplied keys are changed."),
@@ -2693,6 +2698,19 @@ export function registerMetadataTools(s, {
       }
       try {
         const relationshipSnapshot = querySceneRelationshipSnapshot(db, { sceneId: scene_id, projectId: project_id });
+        const needsTagSuggestions = Array.isArray(fields.tags)
+          && fields.tags.some(tag => typeof tag === "string" && Boolean(tag.trim()));
+        const needsBeatSuggestions = typeof fields.save_the_cat_beat === "string"
+          && Boolean(fields.save_the_cat_beat.trim());
+        const fieldSuggestions = needsTagSuggestions || needsBeatSuggestions
+          ? buildFreeformFieldSuggestions({
+              fields,
+              vocabulary: {
+                ...(needsTagSuggestions ? { tags: selectSceneTagVocabulary(db, { projectId: project_id }) } : {}),
+                ...(needsBeatSuggestions ? { beats: selectSceneBeatVocabulary(db, { projectId: project_id }) } : {}),
+              },
+            })
+          : undefined;
         const { sourceMeta } = readSourceMeta(scene.file_path, SYNC_DIR, { writable: true });
         const updated = { ...sourceMeta, ...fields };
         writeMeta(scene.file_path, updated, { syncDir: SYNC_DIR });
@@ -2751,6 +2769,7 @@ export function registerMetadataTools(s, {
           message: `Updated metadata for scene '${scene_id}'.`,
           scene_id,
           project_id,
+          ...(fieldSuggestions ? { field_suggestions: fieldSuggestions } : {}),
           ...backupMutationFields(backupResult),
         });
       } catch (err) {

package/src/tools/search.js

@@ -7,6 +7,15 @@ import {
   upsertExplicitReferenceLinkRow,
 } from "./reference-link-persistence.js";
 import { resolveValidatedChapterFilter } from "../core/chapter-resolution.js";
+import { resolveCharacterTargetForProject } from "../core/canonical-target-resolution.js";
+import {
+  buildVocabularyNoResultsDetails,
+  resolveVocabularyValue,
+  selectSceneBeatCaseVariants,
+  selectSceneBeatVocabulary,
+  selectSceneTagCaseVariants,
+  selectSceneTagVocabulary,
+} from "../core/vocabulary-resolution.js";
 import {
   createToolActor,
   refreshProjectBackupAfterMutation,
@@ -62,6 +71,141 @@ function selectApplyCandidates(enrichedCandidates, selectedDocIds, maxApply) {
   return uniqueCandidates.slice(0, maxApply ?? uniqueCandidates.length);
 }
 
+function resolveCaseInsensitiveChapterId(db, { projectId, chapterId }) {
+  if (!projectId || !chapterId) return { chapterId, resolvedFrom: undefined };
+  const rows = db.prepare(`
+    SELECT chapter_id, title
+    FROM chapters
+    WHERE project_id = ? AND lower(chapter_id) = lower(?)
+    ORDER BY chapter_id
+  `).all(projectId, chapterId);
+  const exactMatch = rows.find(row => row.chapter_id === chapterId);
+  if (exactMatch) {
+    return { chapterId, resolvedFrom: undefined };
+  }
+  if (rows.length > 1) {
+    return {
+      error: {
+        code: "AMBIGUOUS_TARGET",
+        message: `Chapter ID '${chapterId}' resolves to multiple case variants in project '${projectId}'. Use an exact canonical chapter_id.`,
+        details: {
+          lookup_kind: "chapter",
+          target_kind: "chapter",
+          input: chapterId,
+          project_id: projectId,
+          candidate_matches: rows.map(row => ({
+            target_kind: "chapter",
+            id: row.chapter_id,
+            label: row.title || row.chapter_id,
+            matched_field: "chapter_id",
+            match_type: "case_insensitive_id",
+            project_id: projectId,
+          })),
+          next_step: "Use list_chapters to inspect exact chapter_id values, then retry with the intended canonical chapter_id casing.",
+        },
+      },
+    };
+  }
+  if (rows.length !== 1) return { chapterId, resolvedFrom: undefined };
+  return {
+    chapterId: rows[0].chapter_id,
+    resolvedFrom: {
+      chapter_id: {
+        input: chapterId,
+        matched_field: "chapter_id",
+        match_type: "case_insensitive_id",
+        id: rows[0].chapter_id,
+      },
+    },
+  };
+}
+
+function buildIndexedSceneCharacterResolution(rows, { input, argumentName }) {
+  if (rows.length === 0) return undefined;
+  if (rows.length === 1 && rows[0].value !== input) {
+    return {
+      value: rows[0].value,
+      resolved_from: {
+        [argumentName]: {
+          input,
+          matched_field: "character_id",
+          match_type: "case_insensitive_id",
+          id: rows[0].value,
+        },
+      },
+    };
+  }
+  return { value: input, values: rows.map(row => row.value), resolved_from: undefined };
+}
+
+function resolveIndexedSceneCharacterId(db, { projectId, input, argumentName }) {
+  if (!projectId || !input) return undefined;
+  const rows = db.prepare(`
+    SELECT DISTINCT character_id AS value
+    FROM scene_characters
+    WHERE project_id = ? AND character_id IS NOT NULL AND character_id != ''
+      AND lower(character_id) = lower(?)
+    ORDER BY character_id
+  `).all(projectId, input);
+  return buildIndexedSceneCharacterResolution(rows, { input, argumentName });
+}
+
+function resolveIndexedScenePovId(db, { projectId, input, argumentName }) {
+  if (!projectId || !input) return undefined;
+  const rows = db.prepare(`
+    SELECT DISTINCT pov AS value
+    FROM scenes
+    WHERE project_id = ? AND pov IS NOT NULL AND pov != ''
+      AND lower(pov) = lower(?)
+    ORDER BY pov
+  `).all(projectId, input);
+  return buildIndexedSceneCharacterResolution(rows, { input, argumentName });
+}
+
+function mapCharacterResolutionError(errorResponse, resolution, { argumentName, input, projectId }) {
+  return errorResponse(resolution.error.code, resolution.error.message, {
+    ...(resolution.error.details ?? {}),
+    argument: argumentName,
+    input,
+    project_id: projectId,
+  });
+}
+
+function mergeResolvedFilters(...filters) {
+  const merged = {};
+  for (const filter of filters) {
+    if (filter) Object.assign(merged, filter);
+  }
+  return Object.keys(merged).length > 0 ? merged : undefined;
+}
+
+function valuesForVocabularyResolution(resolution, fallback) {
+  if (!resolution.ok) return [fallback];
+  if (Array.isArray(resolution.case_variants) && resolution.case_variants.length > 0) {
+    return resolution.case_variants.map(candidate => candidate.value);
+  }
+  return [resolution.value];
+}
+
+function valuesForIndexedResolution(resolution, fallback) {
+  if (Array.isArray(resolution?.values) && resolution.values.length > 0) {
+    return resolution.values;
+  }
+  if (resolution?.value) return [resolution.value];
+  return fallback ? [fallback] : [];
+}
+
+function addExactValueCondition({ conditions, params, column, values }) {
+  if (!Array.isArray(values) || values.length === 0) return;
+  if (values.length === 1) {
+    conditions.push(`${column} = ?`);
+    params.push(values[0]);
+    return;
+  }
+  conditions.push(`${column} IN (${values.map(() => "?").join(", ")})`);
+  params.push(...values);
+}
+
 export function registerSearchTools(s, {
   db,
   SYNC_DIR,
@@ -79,16 +223,16 @@ export function registerSearchTools(s, {
   // ---- find_scenes ---------------------------------------------------------
   s.tool(
     "find_scenes",
-    "Find scenes by filtering on character, Save the Cat beat, tags, canonical chapter identity, numeric chapter alias, or POV. Returns ordered scene metadata only — no prose. Most filters are optional and combinable. `chapter_id` requires `project_id`; numeric `chapter` is a compatibility alias for read scopes only, resolved through canonical chapter identity, and must agree with `chapter_id` when both are provided. Supports pagination via page/page_size and auto-paginates large result sets with total_count. Warns if any matching scenes have stale metadata. Response shape note: always returns a structured envelope (`results`, `total_count`, with pagination fields when paging is active).",
+    "Find scenes by filtering on character, Save the Cat beat, tags, canonical chapter identity, numeric chapter alias, or POV. Returns ordered scene metadata only — no prose. Most filters are optional and combinable. `character` and `pov` prefer character_id values and may resolve unambiguous project-scoped character names when project_id is provided. `tag` and `beat` match case-insensitively when unambiguous; near matches are suggestion-only. `chapter_id` requires `project_id` and accepts exact canonical IDs or unambiguous case variants; ambiguous case variants return candidate IDs. Numeric `chapter` is a compatibility alias for read scopes only, resolved through canonical chapter identity, and must agree with `chapter_id` when both are provided. Supports pagination via page/page_size and auto-paginates large result sets with total_count. Warns if any matching scenes have stale metadata. Response shape note: always returns a structured envelope (`results`, `total_count`, with pagination fields when paging is active).",
     {
       project_id: z.string().optional().describe("Project ID (e.g. 'the-lamb'). Use to scope results to one project."),
-      character:  z.string().optional().describe("A character_id (e.g. 'char-mira-nystrom'). Returns only scenes that character appears in. Use list_characters first to find valid IDs."),
-      beat:       z.string().optional().describe("Save the Cat beat name (e.g. 'Opening Image'). Exact match."),
-      tag:        z.string().optional().describe("Scene tag to filter by. Exact match."),
+      character:  z.string().optional().describe("A character_id (e.g. 'char-mira-nystrom'), or an unambiguous project-scoped character name when project_id is provided. Returns only scenes that character appears in. Use list_characters first to find valid IDs."),
+      beat:       z.string().optional().describe("Save the Cat beat name (e.g. 'Opening Image'). Matches existing indexed beat values case-insensitively; near matches are suggestions only."),
+      tag:        z.string().optional().describe("Scene tag to filter by. Matches existing indexed tag values case-insensitively; near matches are suggestions only."),
       part:       z.number().int().optional().describe("Part number (integer, e.g. 1). Chapters are numbered globally across the whole project."),
       chapter:    z.number().int().optional().describe("Read-scope compatibility alias resolved from canonical chapter sort order. Not a structural mutation target."),
-      chapter_id: z.string().optional().describe("Canonical chapter identifier. Requires project_id. Use list_chapters to find valid values."),
-      pov:        z.string().optional().describe("POV character_id. Use list_characters first to find valid IDs."),
+      chapter_id: z.string().optional().describe("Canonical chapter identifier. Requires project_id. Case variants of existing chapter_id values are accepted. Use list_chapters to find valid values."),
+      pov:        z.string().optional().describe("POV character_id, or an unambiguous project-scoped character name when project_id is provided. Use list_characters first to find valid IDs."),
       page:       z.number().int().min(1).optional().describe("Optional page number for paginated responses (1-based)."),
       page_size:  z.number().int().min(1).max(200).optional().describe("Optional page size for paginated responses (default: 20, max: 200)."),
     },
@@ -100,8 +244,143 @@ export function registerSearchTools(s, {
           { chapter_id }
         );
       }
-      const resolvedChapterFilter = project_id && (chapter_id || chapter != null)
-        ? resolveValidatedChapterFilter(db, { projectId: project_id, chapterNumber: chapter, chapterId: chapter_id })
+      const resolvedFilters = {};
+      const vocabularySuggestions = [];
+
+      let resolvedCharacter = character;
+      let resolvedCharacterValues = character ? [character] : [];
+      if (project_id && character) {
+        const indexedResolution = resolveIndexedSceneCharacterId(db, {
+          projectId: project_id,
+          input: character,
+          argumentName: "character",
+        });
+        if (indexedResolution) {
+          resolvedCharacter = indexedResolution.value;
+          resolvedCharacterValues = valuesForIndexedResolution(indexedResolution, character);
+          if (indexedResolution.resolved_from?.character) {
+            resolvedFilters.character = indexedResolution.resolved_from.character;
+          }
+        } else {
+          const resolution = resolveCharacterTargetForProject(db, {
+            projectId: project_id,
+            input: character,
+            argumentName: "character",
+          });
+          if (!resolution.ok) {
+            return mapCharacterResolutionError(errorResponse, resolution, {
+              argumentName: "character",
+              input: character,
+              projectId: project_id,
+            });
+          }
+          resolvedCharacter = resolution.character_id;
+          resolvedCharacterValues = [resolution.character_id];
+          if (resolution.resolved_from?.character) {
+            resolvedFilters.character = resolution.resolved_from.character;
+          }
+        }
+      }
+
+      let resolvedPov = pov;
+      let resolvedPovValues = pov ? [pov] : [];
+      if (project_id && pov) {
+        const indexedResolution = resolveIndexedScenePovId(db, {
+          projectId: project_id,
+          input: pov,
+          argumentName: "pov",
+        });
+        if (indexedResolution) {
+          resolvedPov = indexedResolution.value;
+          resolvedPovValues = valuesForIndexedResolution(indexedResolution, pov);
+          if (indexedResolution.resolved_from?.pov) {
+            resolvedFilters.pov = indexedResolution.resolved_from.pov;
+          }
+        } else {
+          const resolution = resolveCharacterTargetForProject(db, {
+            projectId: project_id,
+            input: pov,
+            argumentName: "pov",
+          });
+          if (!resolution.ok) {
+            return mapCharacterResolutionError(errorResponse, resolution, {
+              argumentName: "pov",
+              input: pov,
+              projectId: project_id,
+            });
+          }
+          resolvedPov = resolution.character_id;
+          resolvedPovValues = [resolution.character_id];
+          if (resolution.resolved_from?.pov) {
+            resolvedFilters.pov = resolution.resolved_from.pov;
+          }
+        }
+      }
+
+      let resolvedTag = tag;
+      let resolvedTagValues = tag ? [tag] : [];
+      if (tag) {
+        const tagCaseVariants = selectSceneTagCaseVariants(db, { projectId: project_id, input: tag });
+        const resolution = resolveVocabularyValue({
+          input: tag,
+          values: tagCaseVariants.length > 0
+            ? tagCaseVariants
+            : selectSceneTagVocabulary(db, { projectId: project_id }),
+          targetKind: "tag",
+          matchedField: "tag",
+        });
+        if (resolution.ok) {
+          resolvedTag = resolution.value;
+          resolvedTagValues = valuesForVocabularyResolution(resolution, tag);
+          if (resolution.resolved_from) resolvedFilters.tag = resolution.resolved_from;
+        } else if (resolution.candidate_matches.length > 0) {
+          vocabularySuggestions.push({
+            filter: "tag",
+            input: tag,
+            candidate_matches: resolution.candidate_matches,
+          });
+        }
+      }
+
+      let resolvedBeat = beat;
+      let resolvedBeatValues = beat ? [beat] : [];
+      if (beat) {
+        const beatCaseVariants = selectSceneBeatCaseVariants(db, { projectId: project_id, input: beat });
+        const resolution = resolveVocabularyValue({
+          input: beat,
+          values: beatCaseVariants.length > 0
+            ? beatCaseVariants
+            : selectSceneBeatVocabulary(db, { projectId: project_id }),
+          targetKind: "beat",
+          matchedField: "save_the_cat_beat",
+        });
+        if (resolution.ok) {
+          resolvedBeat = resolution.value;
+          resolvedBeatValues = valuesForVocabularyResolution(resolution, beat);
+          if (resolution.resolved_from) resolvedFilters.beat = resolution.resolved_from;
+        } else if (resolution.candidate_matches.length > 0) {
+          vocabularySuggestions.push({
+            filter: "beat",
+            input: beat,
+            candidate_matches: resolution.candidate_matches,
+          });
+        }
+      }
+
+      const chapterResolution = resolveCaseInsensitiveChapterId(db, { projectId: project_id, chapterId: chapter_id });
+      if (chapterResolution.error) {
+        return errorResponse(
+          chapterResolution.error.code,
+          chapterResolution.error.message,
+          chapterResolution.error.details
+        );
+      }
+      if (chapterResolution.resolvedFrom?.chapter_id) {
+        resolvedFilters.chapter_id = chapterResolution.resolvedFrom.chapter_id;
+      }
+
+      const resolvedChapterFilter = project_id && (chapterResolution.chapterId || chapter != null)
+        ? resolveValidatedChapterFilter(db, { projectId: project_id, chapterNumber: chapter, chapterId: chapterResolution.chapterId })
         : { chapter: null };
       if (resolvedChapterFilter.error) {
         return errorResponse(
@@ -126,16 +405,33 @@ export function registerSearchTools(s, {
       const conditions = [];
       const params = [];
 
-      if (character) {
-        joins.push(`JOIN scene_characters sc ON sc.scene_id = s.scene_id AND sc.project_id = s.project_id AND sc.character_id = ?`);
-        params.push(character);
+      if (resolvedCharacter) {
+        if (resolvedCharacterValues.length === 1) {
+          joins.push(`JOIN scene_characters sc ON sc.scene_id = s.scene_id AND sc.project_id = s.project_id AND sc.character_id = ?`);
+          params.push(resolvedCharacterValues[0]);
+        } else {
+          joins.push(`JOIN scene_characters sc ON sc.scene_id = s.scene_id AND sc.project_id = s.project_id AND sc.character_id IN (${resolvedCharacterValues.map(() => "?").join(", ")})`);
+          params.push(...resolvedCharacterValues);
+        }
       }
-      if (tag) {
-        joins.push(`JOIN scene_tags st ON st.scene_id = s.scene_id AND st.project_id = s.project_id AND st.tag = ?`);
-        params.push(tag);
+      if (resolvedTag) {
+        if (resolvedTagValues.length === 1) {
+          joins.push(`JOIN scene_tags st ON st.scene_id = s.scene_id AND st.project_id = s.project_id AND st.tag = ?`);
+          params.push(resolvedTagValues[0]);
+        } else {
+          joins.push(`JOIN scene_tags st ON st.scene_id = s.scene_id AND st.project_id = s.project_id AND st.tag IN (${resolvedTagValues.map(() => "?").join(", ")})`);
+          params.push(...resolvedTagValues);
+        }
       }
       if (project_id)  { conditions.push(`s.project_id = ?`);        params.push(project_id); }
-      if (beat)        { conditions.push(`s.save_the_cat_beat = ?`);  params.push(beat); }
+      if (resolvedBeat) {
+        addExactValueCondition({
+          conditions,
+          params,
+          column: "s.save_the_cat_beat",
+          values: resolvedBeatValues,
+        });
+      }
       if (part)        { conditions.push(`s.part = ?`);               params.push(part); }
       if (resolvedChapterFilter.chapter) {
         conditions.push(`s.chapter_id = ?`);
@@ -144,7 +440,14 @@ export function registerSearchTools(s, {
         conditions.push(`s.chapter = ?`);
         params.push(chapter);
       }
-      if (pov)         { conditions.push(`s.pov = ?`);                params.push(pov); }
+      if (resolvedPov) {
+        addExactValueCondition({
+          conditions,
+          params,
+          column: "s.pov",
+          values: resolvedPovValues,
+        });
+      }
 
       if (joins.length)      query += " " + joins.join(" ");
       if (conditions.length) query += " WHERE " + conditions.join(" AND ");
@@ -152,7 +455,24 @@ export function registerSearchTools(s, {
 
       const rows = db.prepare(query).all(...params);
       if (rows.length === 0) {
-        return errorResponse("NO_RESULTS", "No scenes match the given filters. Hint: broaden filters or call search_metadata with a keyword first.");
+        return errorResponse(
+          "NO_RESULTS",
+          "No scenes match the given filters. Hint: broaden filters, choose a suggested candidate, or call search_metadata with a keyword first.",
+          buildVocabularyNoResultsDetails({
+            filters: {
+              project_id: project_id ?? null,
+              character: character ?? null,
+              beat: beat ?? null,
+              tag: tag ?? null,
+              part: part ?? null,
+              chapter: chapter ?? null,
+              chapter_id: chapter_id ?? null,
+              pov: pov ?? null,
+            },
+            resolvedFilters: mergeResolvedFilters(resolvedFilters),
+            suggestions: vocabularySuggestions,
+          })
+        );
       }
 
       const staleCount = rows.filter(r => r.metadata_stale).length;
@@ -171,6 +491,7 @@ export function registerSearchTools(s, {
             results: paged.rows,
             ...paged.meta,
             warning,
+            resolved_filters: mergeResolvedFilters(resolvedFilters),
             next_step: staleCount > 0
               ? "Touch stale scenes as you work and run enrich_scene(scene_id, project_id) to recover metadata parity incrementally."
               : undefined,
@@ -179,6 +500,7 @@ export function registerSearchTools(s, {
             results: rows,
             total_count: rows.length,
             warning,
+            resolved_filters: mergeResolvedFilters(resolvedFilters),
             next_step: staleCount > 0
               ? "Touch stale scenes as you work and run enrich_scene(scene_id, project_id) to recover metadata parity incrementally."
               : undefined,