@ssobig/writer-cli 0.3.0 → 0.3.3

package/templates/mystery-v1/timeline-model.js

@@ -0,0 +1,235 @@
+(function (root, factory) {
+  const api = factory();
+  if (typeof module === "object" && module.exports) module.exports = api;
+  if (root) root.WriterWorkbenchTimelineModel = api;
+})(typeof globalThis !== "undefined" ? globalThis : this, function () {
+  "use strict";
+
+  const MINUTES_PER_DAY = 1440;
+  const DEFAULT_LEVEL_NAME = "타임라인";
+  const DEFAULT_GAP_MINUTES = 60;
+
+  function isObject(value) { return Boolean(value && typeof value === "object" && !Array.isArray(value)); }
+  function text(value) { return typeof value === "string" ? value : ""; }
+  function compareNumbers(left, right) { return left === right ? 0 : left < right ? -1 : 1; }
+
+  // events는 사건이 시간을 소유하는 legacy 모양, timeLevels/entries는 항목이 시간을 소유하는 v2 모양이다.
+  function detectShape(data) {
+    if (!isObject(data)) return "invalid";
+    const events = Array.isArray(data.events);
+    const levels = Array.isArray(data.timeLevels);
+    const entries = Array.isArray(data.entries);
+    if (events && !levels && !entries) return "legacy";
+    if (!events && levels && entries) return "v2";
+    return "invalid";
+  }
+
+  function resolveIdFactory(options) {
+    if (typeof options?.idFactory === "function") return options.idFactory;
+    const cryptoApi = typeof globalThis !== "undefined" ? globalThis.crypto : null;
+    if (!cryptoApi || typeof cryptoApi.randomUUID !== "function") throw new Error("UUID 생성 기능을 사용할 수 없어 타임라인을 변환할 수 없습니다.");
+    return () => cryptoApi.randomUUID();
+  }
+
+  function memoryEntries(value) { return isObject(value) ? Object.entries(value) : []; }
+
+  // legacy 변환은 시간 문자열을 해석하지 않고 timeLabel에 원문을 그대로 보존한다.
+  function legacyDescriptors(data) {
+    const descriptors = [];
+    for (const event of data.events) {
+      const base = { timeLabel: text(event?.time), location: text(event?.location), eventGroupId: event?.id };
+      // 본문이 비어 있어도 사건 행의 시간·장소를 보존하기 위해 truth 항목은 항상 만든다.
+      descriptors.push({ ...base, laneKind: "truth", laneRef: "", text: text(event?.truth), included: true });
+      for (const [characterId, memory] of memoryEntries(event?.memories)) {
+        descriptors.push({ ...base, laneKind: "character", laneRef: characterId, text: text(memory?.text), included: memory?.included === true });
+      }
+      for (const [sourceKey, memory] of memoryEntries(event?.unassignedMemories)) {
+        descriptors.push({ ...base, laneKind: "unresolved", laneRef: sourceKey, text: text(memory?.text), included: memory?.included === true });
+      }
+    }
+    return descriptors;
+  }
+
+  function entryDescriptor(entry) {
+    const lane = isObject(entry?.lane) ? entry.lane : {};
+    const laneKind = text(lane.kind);
+    return {
+      laneKind,
+      laneRef: text(laneKind === "character" ? lane.characterId : laneKind === "unresolved" ? lane.sourceKey : ""),
+      timeLabel: text(entry?.timeLabel),
+      location: text(entry?.location),
+      text: text(entry?.text),
+      included: entry?.included === true,
+      eventGroupId: entry?.eventGroupId
+    };
+  }
+
+  function laneOf(descriptor) {
+    if (descriptor.laneKind === "character") return { kind: "character", characterId: descriptor.laneRef };
+    if (descriptor.laneKind === "unresolved") return { kind: "unresolved", sourceKey: descriptor.laneRef };
+    return { kind: "truth" };
+  }
+
+  function convertLegacyTimeline(data, options = {}) {
+    if (detectShape(data) !== "legacy") throw new Error("legacy 타임라인 data가 아닙니다.");
+    const nextId = resolveIdFactory(options);
+    const level = { id: nextId(), name: DEFAULT_LEVEL_NAME, mode: "manual" };
+    const entries = legacyDescriptors(data).map(descriptor => {
+      const entry = {
+        id: nextId(),
+        timeLevelId: level.id,
+        lane: laneOf(descriptor),
+        when: { kind: "unspecified" },
+        timeLabel: descriptor.timeLabel,
+        location: descriptor.location,
+        text: descriptor.text,
+        included: descriptor.included
+      };
+      if (typeof descriptor.eventGroupId === "string") entry.eventGroupId = descriptor.eventGroupId;
+      return entry;
+    });
+    return { timeLevels: [level], entries };
+  }
+
+  // 이관 CLI가 사람 검토 리포트로 쓰는 무손실 전수 대조다.
+  function compareLegacyToV2(legacyData, v2Data) {
+    const counts = { truthEntries: 0, memoryEntries: 0, unresolvedEntries: 0, includedTrue: 0 };
+    const mismatches = [];
+    if (detectShape(legacyData) !== "legacy") mismatches.push("원본이 legacy 타임라인 data가 아닙니다.");
+    if (detectShape(v2Data) !== "v2") mismatches.push("대상이 v2 타임라인 data가 아닙니다.");
+    if (mismatches.length) return { ok: false, counts, mismatches };
+
+    for (const entry of v2Data.entries) {
+      const descriptor = entryDescriptor(entry);
+      if (descriptor.laneKind === "truth") counts.truthEntries += 1;
+      if (descriptor.laneKind === "character") counts.memoryEntries += 1;
+      if (descriptor.laneKind === "unresolved") counts.unresolvedEntries += 1;
+      if (descriptor.included) counts.includedTrue += 1;
+    }
+
+    const expected = legacyDescriptors(legacyData);
+    if (expected.length !== v2Data.entries.length) {
+      mismatches.push(`항목 수가 다릅니다: 원본 ${expected.length}개, 변환 ${v2Data.entries.length}개`);
+    }
+    const levelIds = new Set(v2Data.timeLevels.map(level => level.id));
+    for (let index = 0; index < Math.min(expected.length, v2Data.entries.length); index += 1) {
+      const before = expected[index];
+      const after = entryDescriptor(v2Data.entries[index]);
+      for (const name of ["laneKind", "laneRef", "timeLabel", "location", "text", "included", "eventGroupId"]) {
+        if (before[name] !== after[name]) mismatches.push(`${index}번째 항목의 ${name}이(가) 다릅니다: ${JSON.stringify(before[name])} → ${JSON.stringify(after[name])}`);
+      }
+      if (!levelIds.has(v2Data.entries[index].timeLevelId)) mismatches.push(`${index}번째 항목이 존재하지 않는 시간 레벨을 가리킵니다.`);
+    }
+    return { ok: mismatches.length === 0, counts, mismatches };
+  }
+
+  function clockMinute(entry) {
+    const when = isObject(entry?.when) ? entry.when : {};
+    if (when.kind !== "clock" || !Number.isSafeInteger(when.startMinute)) return null;
+    const dayOffset = Number.isSafeInteger(when.dayOffset) ? when.dayOffset : 0;
+    const endMinute = Number.isSafeInteger(when.endMinute) ? when.endMinute : when.startMinute;
+    return { dayOffset, startMinute: when.startMinute, endMinute, start: dayOffset * MINUTES_PER_DAY + when.startMinute, end: dayOffset * MINUTES_PER_DAY + endMinute };
+  }
+
+  // 저장 데이터는 바꾸지 않는 보기 전용 순서다.
+  function orderedEntries(v2Data) {
+    if (detectShape(v2Data) !== "v2") throw new Error("v2 타임라인 data가 아닙니다.");
+    const levelOrder = new Map(v2Data.timeLevels.map((level, index) => [level.id, index]));
+    return v2Data.entries
+      .map((entry, index) => {
+        const clock = clockMinute(entry);
+        return {
+          entry,
+          index,
+          level: levelOrder.has(entry.timeLevelId) ? levelOrder.get(entry.timeLevelId) : Number.POSITIVE_INFINITY,
+          minute: clock ? clock.start : Number.POSITIVE_INFINITY
+        };
+      })
+      .sort((left, right) => compareNumbers(left.level, right.level) || compareNumbers(left.minute, right.minute) || compareNumbers(left.index, right.index))
+      .map(item => item.entry);
+  }
+
+  function clockItems(entries) {
+    return (Array.isArray(entries) ? entries : [])
+      .map((entry, index) => ({ entry, index, clock: clockMinute(entry) }))
+      .filter(item => item.clock)
+      .sort((left, right) => compareNumbers(left.clock.start, right.clock.start) || compareNumbers(left.index, right.index));
+  }
+
+  // [start, end) 구간이 겹치는 묶음. endMinute이 없는 항목은 1분 점으로 취급해 시작 시각만 비교한다.
+  function overlapGroups(entries) {
+    const byLevel = new Map();
+    for (const item of clockItems(entries)) {
+      const levelId = item.entry.timeLevelId;
+      if (!byLevel.has(levelId)) byLevel.set(levelId, []);
+      byLevel.get(levelId).push(item);
+    }
+    const groups = [];
+    for (const items of byLevel.values()) {
+      let current = null;
+      for (const item of items) {
+        const exclusiveEnd = Math.max(item.clock.end, item.clock.start + 1);
+        if (current && item.clock.start < current.exclusiveEnd) {
+          current.entryIds.push(item.entry.id);
+          current.startMinute = Math.min(current.startMinute, item.clock.start);
+          current.endMinute = Math.max(current.endMinute, item.clock.end);
+          current.exclusiveEnd = Math.max(current.exclusiveEnd, exclusiveEnd);
+          continue;
+        }
+        if (current && current.entryIds.length > 1) groups.push(current);
+        current = { entryIds: [item.entry.id], startMinute: item.clock.start, endMinute: item.clock.end, exclusiveEnd };
+      }
+      if (current && current.entryIds.length > 1) groups.push(current);
+    }
+    return groups.map(group => ({ entryIds: group.entryIds, startMinute: group.startMinute, endMinute: group.endMinute }));
+  }
+
+  // 시작 시각 공백이 gapMinutes를 넘으면 분리한 로컬 시간 묶음.
+  // startMinute/endMinute은 묶음의 dayOffset을 기준으로 한 로컬 분이며, 날짜를 넘는 묶음은 endMinute이 1439를 넘을 수 있다.
+  function deriveClusters(entries, options = {}) {
+    const gapMinutes = Number.isFinite(options.gapMinutes) ? options.gapMinutes : DEFAULT_GAP_MINUTES;
+    const clusters = [];
+    let current = null;
+    for (const item of clockItems(entries)) {
+      if (current && item.clock.start - current.end <= gapMinutes) {
+        current.entryIds.push(item.entry.id);
+        current.end = Math.max(current.end, item.clock.end);
+        continue;
+      }
+      if (current) clusters.push(current);
+      current = { dayOffset: item.clock.dayOffset, start: item.clock.start, end: item.clock.end, entryIds: [item.entry.id] };
+    }
+    if (current) clusters.push(current);
+    return clusters.map(cluster => ({
+      startMinute: cluster.start - cluster.dayOffset * MINUTES_PER_DAY,
+      endMinute: cluster.end - cluster.dayOffset * MINUTES_PER_DAY,
+      dayOffset: cluster.dayOffset,
+      entryIds: cluster.entryIds
+    }));
+  }
+
+  // 항목이 표시할 장소 이름. placeIds가 가리키는 장소를 이동 경로 순서 그대로 돌려주고,
+  // 그 결과가 비면 전환기 fallback인 location 문자열을 쓴다. 둘 다 비면 빈 배열이다.
+  function entryPlaceNames(data, entry) {
+    const places = isObject(data) && Array.isArray(data.places) ? data.places : [];
+    const names = new Map(places
+      .filter(place => isObject(place) && typeof place.id === "string")
+      .map(place => [place.id.toLowerCase(), text(place.name)]));
+    const referenced = (Array.isArray(entry?.placeIds) ? entry.placeIds : [])
+      .map(id => (typeof id === "string" ? text(names.get(id.toLowerCase())) : ""))
+      .filter(name => name.trim());
+    if (referenced.length) return referenced;
+    const location = text(entry?.location).trim();
+    return location ? [location] : [];
+  }
+
+  // 활성 런타임이 중립 이름으로 소비하는 정규화 진입점: 어떤 등록 모양이든 v2 data를 돌려준다.
+  function normalizedTimelineData(data, options = {}) {
+    const shape = detectShape(data);
+    if (shape === "v2") return data;
+    if (shape === "legacy") return convertLegacyTimeline(data, options);
+    throw new Error("타임라인 data가 등록된 모양이 아닙니다.");
+  }
+
+  return Object.freeze({ detectShape, convertLegacyTimeline, compareLegacyToV2, normalizedTimelineData, entryPlaceNames, orderedEntries, overlapGroups, deriveClusters });
+});

package/tools/writer-cli/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@ssobig/writer-cli",
-  "version": "0.3.0",
+  "version": "0.3.3",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@ssobig/writer-cli",
-      "version": "0.3.0",
+      "version": "0.3.3",
       "dependencies": {
         "@supabase/supabase-js": "2.110.9"
       },

package/tools/writer-cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ssobig/writer-cli",
-  "version": "0.3.0",
+  "version": "0.3.3",
   "private": true,
   "description": "Internal agent-safe CLI for SSOBIG WRITER manuscript and asset operations",
   "type": "commonjs",

package/tools/writer-cli/skills/ssobig-writer-cli/SKILL.md

@@ -5,7 +5,7 @@ description: Safely discover and use the public SSOBIG WRITER CLI for manuscript
 
 # SSOBIG WRITER CLI
 
-Use this skill when a task asks you to inspect or change a Writer project through `ssobig-writer`. Treat the CLI, not this document, as the source of truth for command syntax. Start with the narrowest discovery call that answers the question:
+Use this skill when a task asks you to inspect or change a Writer project through `ssobig-writer`. Treat the CLI, not this document, as the source of truth for command syntax. When syntax is uncertain, choose the narrowest discovery call below; these are alternatives, not a required sequence:
 
 ```bash
 ssobig-writer <group> --help
@@ -17,22 +17,21 @@ Do not dump the complete schema when one group or leaf is enough. The root schem
 
 Route by intent and read only the relevant reference:
 
-- Installation, sign-in, diagnostics, updates, or project-local skill setup: `references/install-auth.md`
-- Finding manuscript values or reading targeted Component data: `references/read-search.md`
-- Project identity, versions, Component reads, and reviewed data plans: `references/projects-components.md`
-- Asset pointers, checkpoint history, restore plans, and receipts: `references/assets-checkpoints.md`
-- Any failure, conflict, authorization issue, or boundary response: `references/errors.md`
+- Installation, sign-in, diagnostics, updates, or project-local skill setup: [references/install-auth.md](references/install-auth.md)
+- Finding manuscript values or reading targeted Component data: [references/read-search.md](references/read-search.md)
+- Project identity, versions, Component reads, and reviewed data plans: [references/projects-components.md](references/projects-components.md)
+- Asset pointers, checkpoint history, restore plans, and receipts: [references/assets-checkpoints.md](references/assets-checkpoints.md)
+- Investigation-board layout specs and review: [references/investigation-board.md](references/investigation-board.md)
+- Any failure, conflict, authorization issue, or boundary response: [references/errors.md](references/errors.md)
 
 The authoritative manuscript source is Writer Component data. Never bypass the CLI with raw SQL, generic database updates, a Supabase management client, or a service-role credential. Never place manuscript values in source code, View HTML/JavaScript, local caches, or ad-hoc JSON as a substitute for Component data.
 
-For every production mutation, follow this sequence without shortcuts:
+For content changes, use `plan -> human-readable review -> apply -> authoritative read-back`. Read the target on the server and prepare a dedicated `plan-*` result; planning does not change production data. Present the exact target, before/after changes, and material effects before apply.
 
-1. Read the authoritative current state.
-2. Create a plan with the dedicated `plan-*` command.
-3. Present a human-readable review of the exact target and changes.
-4. Run `apply` only after the user explicitly authorizes that mutation.
-5. Read the authoritative state again and retain the receipt privately.
+Apply requires an explicit request to change Writer data. Existing authorization remains valid for the same target and scope; do not ask again merely because a plan was generated. Ask when a material decision remains unresolved or the proposed mutation exceeds that scope. A request to inspect, explain, or prepare a plan does not authorize apply. A plan digest is an integrity checksum, not evidence of approval.
 
-A general request to inspect code or explain behavior does not authorize manuscript mutation. Plan and receipt files can contain confidential content; store them in a private ignored directory and never commit them.
+Successful apply already performs authoritative read-back and returns verified receipt fields. Inspect those fields against the intended change; use an additional targeted read when values or an uncertain outcome need inspection, and UI verification when the task concerns visible behavior. Do not automatically repeat a full validation after every successful apply. See the relevant reference for operation-specific completion criteria.
+
+Plans, specs, patches, and receipts can contain confidential content; keep them under ignored `.ssobig-writer/` paths or another private directory and never commit them.
 
 `E_CODE_CHANGE_REQUIRED` is a hard stop. Supported Component-management mutations are registered optional Component addition through `component plan-add`, archive/restore through `component plan-set-active`, and registered optional-field selection through `component plan-set-field`. Shared schemas, unregistered composition, reorder behavior, Renderer/View behavior, identity, and other boundaries remain outside the content CLI. Do not work around them.

package/tools/writer-cli/skills/ssobig-writer-cli/references/assets-checkpoints.md

@@ -2,4 +2,8 @@
 
 Asset pointers are owned by the dedicated asset Component. Use only `asset plan-upload` or `asset plan-delete`; do not patch pointers through generic Component data. Validate the selected project, asset ID, file type, and expected prior entry before review and apply.
 
-Checkpoint commands provide history, snapshots, diffs, creation plans, and restore plans. A restore is a production mutation and follows plan, review, explicit authorization, apply, authoritative read-back. Keep plan and receipt files private. Use `checkpoint diff` to make the review understandable before a restore.
+Checkpoint commands provide history, snapshots, diffs, creation plans, and restore plans. Creation and restore are production mutations; use the common review/authorization rules in [SKILL.md](../SKILL.md). Keep plan and receipt files private. Use `checkpoint diff` to make the review understandable before a restore.
+
+Asset delete disconnects the pointer with a tombstone; it does not physically delete a committed Storage object. Upload success alone is not completion: apply must verify the manifest pointer and revision. Image rendering requires a separate UI check when requested.
+
+Checkpoint `show` and `diff` hide manuscript values by default. Request `--include-data` or `--include-values` only when needed for the review. Checkpoint restore read-back verifies restored content and checkpoint metadata; it does not restore arbitrary incompatible schemas/composition.

package/tools/writer-cli/skills/ssobig-writer-cli/references/errors.md

@@ -1,7 +1,10 @@
 # Errors and boundaries
 
-- `E_CLI_UPDATE_REQUIRED`: the original operation was not sent. Follow the returned npm `installCommand`; ZIP installers are unsupported. Then run the returned `skillCommands.status`, use `skillCommands.install` when missing or `skillCommands.update` when `update-available`, and start a new agent task before retrying.
+- `E_CLI_UPDATE_REQUIRED`: the original operation was not sent. Follow the returned npm `installCommand`; ZIP installers are unsupported. Use its returned `skillCommands.status`, `skillCommands.install`, and `skillCommands.update` as applicable; follow [the update lifecycle](install-auth.md) without repeating a completed version check.
 - `E_CODE_CHANGE_REQUIRED`: hard boundary; do not use SQL or another client. Separate a code or migration task.
+- `E_AMBIGUOUS_SAVE`: the write may have committed. Do not reapply the same plan or automatically retry. Read the affected Component, asset manifest, project status, or checkpoint history on the server and compare the observed result with the plan/receipt before deciding the next action. A timeout is not proof of failure.
+- `E_MATCH_STALE`: refresh the index/search and create a new plan from the current match.
+- `E_DAEMON_REQUEST_TIMEOUT`: a read-only request timed out; retry a read if useful. Mutation timeouts become `E_AMBIGUOUS_SAVE` and follow the rule above.
 - `E_CONFLICT`: authoritative data changed after the plan. Read again and create a new plan.
 - `E_AUTH_REQUIRED`, `E_AUTH_EXPIRED`, `E_AUTHORIZATION`: use the supported login flow or ask an authorized staff member; never handle tokens directly.
 - `E_SKILL_CONFLICT`: an unmanaged or user-modified skill file is present. Preserve it and inspect status/diff; do not overwrite it.

package/tools/writer-cli/skills/ssobig-writer-cli/references/install-auth.md

@@ -4,9 +4,9 @@ Use targeted help for `version`, `doctor`, `auth`, and `skills`. Install the npm
 
 Check `version --check` before long work. From CLI 0.2.0 onward, outdated server-access commands stop with `E_CLI_UPDATE_REQUIRED`; local help, schemas, diagnostics, logout, daemon cleanup, and skill management remain available. Registry outages fail open unless a cached newer version is already known.
 
-Follow this complete lifecycle whenever the CLI reports an update:
+When an update is required, resume at the first unfinished step:
 
-1. Run `ssobig-writer version --check` and preserve its sanitized `registry.remediation` details. The equivalent `doctor` check exposes the same lifecycle as additive `remediationDetails`, while keeping its existing remediation string.
+1. If no current update result is available, run `ssobig-writer version --check`. Otherwise reuse the sanitized remediation from `E_CLI_UPDATE_REQUIRED`, `version`, or `doctor`; do not repeat the check.
 2. Update with `npm install --global @ssobig/writer-cli@latest`. npm is the only supported distribution channel; do not look for or use ZIP installers.
 3. Run `ssobig-writer skills status --target <workspace>` from the updated CLI.
 4. If the skill is missing, run `ssobig-writer skills install --target <workspace>`. If it reports `update-available`, run `ssobig-writer skills update --target <workspace>`. Do nothing when it reports `current`.
@@ -16,4 +16,4 @@ Updating the global CLI never silently changes a workspace. Keep this explicit s
 
 Before uninstalling the CLI, preview project-local skill removal with `ssobig-writer skills remove --target <workspace> --managed-only --dry-run`. If the preview owns only the expected managed files, run it again without `--dry-run`, then uninstall the npm package. Never delete an entire `.agents/skills` or `.claude/skills` directory.
 
-Authentication uses the supported staff flow. Never request, print, persist, or transmit access tokens. Use `doctor` for sanitized installation, credential-store, network, update, and daemon-version diagnostics.
+Authentication uses Google sign-in for Writer members. Project owner/editor/viewer permissions determine access; administrative operations retain their separate authorization checks. Never request, print, persist, or transmit access tokens. Use `doctor` for sanitized installation, credential-store, network, update, and daemon-version diagnostics.

package/tools/writer-cli/skills/ssobig-writer-cli/references/investigation-board.md

@@ -0,0 +1,9 @@
+# Investigation-board plans
+
+Read [layout-spec.md](layout-spec.md) before authoring a spec; it contains the complete contract and a generic example. Read the board and any referenced characters/clues through `component get`, and use their stable IDs. If the board is missing or archived, inspect `component list`: a registered addable/restorable board uses its dedicated reviewed `plan-add`/`plan-set-active` operation when within the requested scope. Unregistered composition remains a code boundary.
+
+Write a semantic spec under `.ssobig-writer/`, then use `component plan-layout-investigation-board --project <slug> --spec <private-spec-file> --out <private-plan-file>`. The command generates a local plan and does not save Writer data. It replaces the board's complete `viewport`, `nodes`, and `edges`; disclose this effect in the review.
+
+Use the center cluster for the main conflict or anchors, primary nodes for visual emphasis, and short relationship labels. Aim for at most 24 nodes and seven primary edges in an overview; these are readability targets, not schema limits. Inspect `layout.review` for crossings, card intersections, long edges, orphans, and quality warnings. Revise semantic grouping/order when the review exposes a problem; do not hand-edit generated coordinates.
+
+Use the common authorization rules in [SKILL.md](../SKILL.md). After successful apply, inspect the verified receipt. Read the board when you need to compare values, and inspect the rendered board when visual readability is part of the request; a quality score alone does not prove the rendered result. Use `validate` to diagnose unresolved composition/schema issues, not as an automatic duplicate of successful apply validation.

package/tools/writer-cli/skills/ssobig-writer-cli/references/layout-spec.md

@@ -0,0 +1,130 @@
+# Investigation board semantic layout spec
+
+Use schema version `ssobig-investigation-board-layout-v1`. This file describes meaning and reading order; `component plan-layout-investigation-board` converts it into strict `ssobig.investigation-board@1` data with deterministic coordinates, sizes, and colors.
+
+## Top-level contract
+
+```json
+{
+  "schemaVersion": "ssobig-investigation-board-layout-v1",
+  "layout": "hub-clusters",
+  "clusters": [],
+  "nodes": [],
+  "edges": []
+}
+```
+
+- `clusters`: 2–5 entries. Each uses a unique `band`; `center` is required.
+- `nodes`: 2–38 entries. Every cluster must contain at least one node.
+- `edges`: 1–120 entries.
+- IDs use letters, numbers, `.`, `_`, `:`, or `-`, begin with a letter or number, and are at most 128 characters.
+- Unknown fields are rejected. Do not include generated board fields such as coordinates, sizes, or colors.
+
+## Clusters
+
+Each cluster has:
+
+```json
+{ "id": "core", "label": "핵심 갈등", "band": "center" }
+```
+
+Allowed bands are `top`, `left`, `center`, `right`, and `bottom`. Use one cluster per band. Capacity is 8 nodes in `top`, `left`, `right`, and `bottom`, and 6 nodes in `center`.
+
+A practical overview uses:
+
+- `center`: main characters, central 사건, or the primary contradiction;
+- `top`: past event, premise, or upstream cause;
+- `left` and `right`: competing statements, factions, or evidence groups;
+- `bottom`: consequences, unresolved questions, or the current hypothesis.
+
+## Nodes
+
+All nodes require `id`, `type`, `clusterId`, `order`, `importance`, and `semantic`.
+
+Reference node:
+
+```json
+{
+  "id": "character-a",
+  "type": "reference",
+  "clusterId": "core",
+  "order": 0,
+  "importance": "primary",
+  "semantic": "character",
+  "referenceType": "character",
+  "referenceId": "stable-character-key"
+}
+```
+
+Sticky node:
+
+```json
+{
+  "id": "contradiction-a",
+  "type": "sticky",
+  "clusterId": "statements",
+  "order": 0,
+  "importance": "secondary",
+  "semantic": "question",
+  "title": "시간 모순",
+  "text": "두 진술의 사건 시간이 일치하지 않는다."
+}
+```
+
+Rules:
+
+- `order` is a unique integer from 0 to 999 inside a cluster. It controls deterministic grid order.
+- `importance` is `primary` or `secondary` and controls card size.
+- `semantic` is `character`, `evidence`, `question`, `allegation`, `fact`, or `context`; it controls the shared palette.
+- A character reference must use `semantic: "character"`. A clue reference cannot use `character`. A sticky cannot use `character`.
+- `referenceType` is `character` or `clue`. `referenceId` must already exist in the authoritative work. A clue reference uses the canonical clue UUID `id` only.
+- Sticky `title` is at most 120 characters and `text` is at most 5,000 characters.
+
+## Edges
+
+Each edge has:
+
+```json
+{
+  "id": "relation-a",
+  "fromNodeId": "character-a",
+  "toNodeId": "contradiction-a",
+  "order": 0,
+  "direction": "forward",
+  "label": "진술이 모순됨",
+  "kind": "evidence"
+}
+```
+
+- `order` is globally unique from 0 to 999.
+- `direction` is `none`, `forward`, or `both`.
+- `label` is non-empty and at most 200 characters.
+- `kind` is `primary`, `causal`, `claim`, `evidence`, or `context`; it controls line color and stored order.
+- Use `primary` only for the relationships someone must understand at first glance. Keep labels short and concrete.
+
+## Complete generic example
+
+```json
+{
+  "schemaVersion": "ssobig-investigation-board-layout-v1",
+  "layout": "hub-clusters",
+  "clusters": [
+    { "id": "core", "label": "핵심 인물", "band": "center" },
+    { "id": "past", "label": "과거 사건", "band": "top" },
+    { "id": "evidence", "label": "증거와 진술", "band": "right" }
+  ],
+  "nodes": [
+    { "id": "person-a", "type": "reference", "clusterId": "core", "order": 0, "importance": "primary", "semantic": "character", "referenceType": "character", "referenceId": "stable-character-a" },
+    { "id": "person-b", "type": "reference", "clusterId": "core", "order": 1, "importance": "primary", "semantic": "character", "referenceType": "character", "referenceId": "stable-character-b" },
+    { "id": "past-event", "type": "sticky", "clusterId": "past", "order": 0, "importance": "primary", "semantic": "fact", "title": "과거 사건", "text": "현재 갈등의 원인이 된 사건" },
+    { "id": "open-question", "type": "sticky", "clusterId": "evidence", "order": 0, "importance": "secondary", "semantic": "question", "title": "확인할 점", "text": "두 진술의 시간이 왜 다른가?" }
+  ],
+  "edges": [
+    { "id": "main-conflict", "fromNodeId": "person-a", "toNodeId": "person-b", "order": 0, "direction": "both", "label": "대립", "kind": "primary" },
+    { "id": "past-cause", "fromNodeId": "past-event", "toNodeId": "person-a", "order": 1, "direction": "forward", "label": "동기", "kind": "causal" },
+    { "id": "question-target", "fromNodeId": "open-question", "toNodeId": "person-b", "order": 2, "direction": "forward", "label": "진술 확인", "kind": "evidence" }
+  ]
+}
+```
+
+Replace the generic stable IDs only after authoritative CLI reads. The algorithm version `hub-clusters-v1` always generates the same board data and review for the same normalized spec and reference catalog.

package/tools/writer-cli/skills/ssobig-writer-cli/references/projects-components.md

@@ -4,4 +4,10 @@ Project commands expose identity, versions, and reviewed project-level plans. Co
 
 Generic Component patching changes only an existing Instance's `data`. Check `component list` for `addableTemplates` and `archivedComponents`. Use `component plan-add` for a never-created registered optional Component, `component plan-set-active` for its data-preserving archive/restore toggle, and `component plan-set-field` for a registered optional field shown in the Component screen. These commands cannot edit arbitrary composition, metadata, View bindings, templates, schemas, project identity, or storage paths. If the CLI returns `E_CODE_CHANGE_REQUIRED`, stop and report that a separate code or migration review is required.
 
-Never apply a generated plan until the user has reviewed a human-readable summary and explicitly authorized the production mutation. Read back the same Component after apply.
+Use the common review/authorization rules in [SKILL.md](../SKILL.md). For Component patches, successful apply verifies planned data, saved revision, Set revision, and the automatic checkpoint. Inspect the receipt; read the Component again if you need actual values. A stored-data receipt does not verify the rendered UI.
+
+Project creation/import, project archive/restore, and Component addition/toggling have different read-back targets. Inspect the resulting identity/status/composition rather than always issuing a Component read. An import receipt can contain `pendingAssets`; import success alone does not mean those assets have been uploaded.
+
+For `component plan-patch`, the RFC 6902 root is Instance `data`; supported operations are `test`, `add`, `replace`, and `remove`. Use authoritative stable IDs and test prior values. Keep patch/plan/receipt files under `.ssobig-writer/`. For a text match, `component plan-replace` creates the guarded patch from a server reread. Use dedicated commands for registered optional fields and timeline migration.
+
+For investigation-board layouts, read [investigation-board.md](investigation-board.md).

package/tools/writer-cli/skills/ssobig-writer-cli/references/read-search.md

@@ -1,5 +1,15 @@
 # Read and search
 
-Start with `search` when the target location is unknown, then use the returned stable identifier with `read`, `component get`, or `agent get`. Prefer exact project, Component, path, and value filters. Use `--fresh` when authoritative refresh is desirable and `--require-fresh` when stale indexed data is unacceptable.
+When the location is unknown, use a scoped `search`; when the project/Instance is known, read it directly. `read` without a Component returns an overview, so a known target does not require a corpus dump or a search first. Inspect leaf help/schema only when syntax is uncertain.
 
-Avoid broad corpus dumps. Inspect exact syntax through `search --help`, `read --help`, or the exact leaf schema. Search and read output may contain confidential manuscript content; summarize only what the task needs.
+| Need | Command and evidence |
+| --- | --- |
+| Locate a value or inspect indexed structure | `search` / `read`: local index; `authoritative: false`, `requiresServerReadBeforeWrite: true`. |
+| Refresh the index now | `--fresh`: syncs the corpus first; output remains an indexed snapshot. |
+| Refresh an index known to be stale | `--require-fresh`: syncs when missing, invalidated, or not marked fresh; it is not a server read on every call. |
+| Read a Component on the server | `component get --project <slug> --instance <id>` |
+| Read a search match on the server | `agent get --match <match-id>`; scalar output is bounded. |
+
+Prefer exact project, Component, path, and value filters. Plan commands reread server state and check revisions/hashes; cached search results never authorize a write. `E_MATCH_STALE` requires a refreshed search and a new plan. After apply the index is invalidated; plain `read` is not proof of the saved value.
+
+Search/read output may contain confidential manuscript content. Summarize only what the task needs.