newo 3.7.2 → 3.7.4

package/CHANGELOG.md

@@ -7,6 +7,35 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.7.4] - 2026-06-10
+
+### Added
+
+- **V2 push now creates new skills from inline flow YAML definitions.** Previously the `newo_v2` push path could only update content of skills already known to the local project map; a skill added locally to `{FlowIdn}.yaml` after the last pull was silently ignored, leaving its `.nsl`/`.nslg` script with no way to reach the platform. `V2ProjectSyncStrategy.push()` now reconciles inline skill metadata before iterating script changes: missing remote skills are created via `POST /api/v1/designer/flows/{flowId}/skills`, race-condition duplicates (already-exists on create) fall back to fetching the remote skill via `listFlowSkills` and updating it, and missing skill parameters are filled in via `POST /api/v1/designer/flows/skills/{skillId}/parameters`. The local project map and SHA256 hash store are updated atomically after the reconciliation pass.
+- **Strict model validation before V2 skill writes.** New `assertSkillModelResolved` helper throws a descriptive error ("Set either skill.model.* or flow default_model_idn/default_provider_idn") when neither the inline skill nor the flow declares a model/provider, instead of letting the platform return a generic 4xx with no hint about which YAML field is missing.
+- **33 unit tests** in `test/v2-push-helpers.test.js` covering `isAlreadyExistsApiError`, `assertSkillModelResolved`, `normalizeRunnerType`, `normalizeParameters`, `skillMetadataDiffers`, `buildV2SkillMetadataFromYaml`, and `createMissingSkillParameters` (stubbed API client). Regression-locks the false-positive matcher fix, the model-validation contract, the parameter-creation counting, and the model-key-order false positive.
+
+### Fixed
+
+- **`isAlreadyExistsApiError` no longer matches "does not exist".** The previous detector accepted any 400/409/422 response whose body contained the substring `"exist"`, which incorrectly classified "Skill does not exist" / "Flow doesn't exist" errors as duplicates and triggered a spurious reuse fallback. The matcher is now tightened to only `"already exists"` and `"duplicate key"`.
+- **`validate()` reports missing scripts for YAML-declared skills.** Previously `V2ProjectSyncStrategy.validate()` only checked scripts listed in the local map; skills added directly to `{FlowIdn}.yaml` since the last pull were never validated. Validation now walks the YAML when present and surfaces a `Script file not found:` error per skill, matching the new push contract.
+- **Missing-script skills are reported, not silently skipped.** Instead of a `verbose`-only "Skipping skill without local script" log, the push now records `[newo_v2] Missing script for skill {project}/{agent}/{flow}/{skill}: {path}` in the push errors. Failures are isolated per skill: one broken skill no longer aborts the push of every other flow/project in the workspace.
+- **Model validation only runs before actual platform writes.** `assertSkillModelResolved` fires only when a skill is about to be created or its metadata updated — a pre-existing flow YAML without `skill.model.*` / flow `default_model_idn` no longer blocks pushes of unrelated, untouched skills.
+- **Parameter-creation count is no longer inflated by already-existing parameters.** `createMissingSkillParameters` incremented its counter (and logged "Created skill parameter") even when the platform answered "already exists", which spuriously triggered a follow-up `updateSkill` call. Count and log now happen only on successful creation.
+- **`isAlreadyExistsApiError` no longer throws on `null`/`undefined` errors** (optional chaining on `.response`), which previously masked the original failure inside catch handlers.
+- **`skillMetadataDiffers` no longer flags every skill as changed.** The model comparison used `JSON.stringify`, which is key-order-sensitive: the project map stores `{provider_idn, model_idn}` (platform API order) while YAML-built metadata uses `{model_idn, provider_idn}`. Verified against a live account: every push rewrote all 1342 skills. Model is now compared field-by-field and parameters are compared order-insensitively (sorted by name).
+- **Skill parameters are now created explicitly after `createSkill`.** The platform's create endpoint ignores inline `parameters` in the request body (verified against the live platform) — newly created skills silently lost their YAML-declared parameters. The create path now calls `POST /flows/skills/{skillId}/parameters` per parameter, same as the update path.
+
+## [3.7.3] - 2026-05-25
+
+### Fixed
+
+- **Workflow Builder canvas blank-screen, take two** - JSON-typed attribute values that contain Markdown body text with `\_` escapes (Builder uses backslash-underscore to escape underscores) and/or structural newlines from pretty-printed JSON no longer corrupt the canvas on push. Two bugs were leaking through v3.7.1's STRING-coercion fix: (a) `yaml.dump` of a pretty-printed JSON string emitted a double-quoted scalar with `\n` escape sequences, which `patchYamlToPyyaml` then rewrote as a single-quoted scalar where `\n` became two literal chars - Builder's `JSON.parse` then choked on backslash-n as structural whitespace; (b) `\_` is not a valid JSON escape per RFC 8259 and Chrome V8's `JSON.parse` throws on it, silently blanking the Builder. Fix: `normalizeJsonValueForStorage` now strips invalid escape sequences via a quote-aware walker (`fixInvalidJsonEscapes`), then compacts via `JSON.parse` + `JSON.stringify` so the value is a single-line string that survives `yaml.dump` -> `patchYamlToPyyaml` without escape-sequence corruption. Existing pretty-printed canvases in `attributes.yaml` will be reformatted to compact form on next pull (one-time stylistic diff, no semantic loss). Change-detection (`jsonValuesEqual`) continues to canonicalize both sides so the new compact form does not trigger spurious pushes against remotes that may still be pretty. Reported by Bob in [#7](https://github.com/sabbah13/newo-cli/pull/7); 25 regression tests in `test/json-attribute-roundtrip.test.js` covering both bug families and the full pull -> dump -> patch -> reload -> `JSON.parse` pipeline.
+
+### Added
+
+- **`fixInvalidJsonEscapes(s)`** in `src/sync/json-attr-utils.ts` - quote-aware walker that strips invalid JSON escape sequences (`\_`, `\.`, etc.) inside JSON string values per RFC 8259. Preserves all valid escapes (`\" \\ \/ \b \f \n \r \t \uXXXX`) and structural characters outside strings.
+
 ## [3.7.2] - 2026-05-17
 
 ### Fixed
@@ -1051,7 +1080,10 @@ Another Item: $Price [Modifiers: modifier3]
 - GitHub Actions CI/CD integration
 - Robust authentication with token refresh
 
-[Unreleased]: https://github.com/sabbah13/newo-cli/compare/v3.7.1...HEAD
+[Unreleased]: https://github.com/sabbah13/newo-cli/compare/v3.7.4...HEAD
+[3.7.4]: https://github.com/sabbah13/newo-cli/compare/v3.7.3...v3.7.4
+[3.7.3]: https://github.com/sabbah13/newo-cli/compare/v3.7.2...v3.7.3
+[3.7.2]: https://github.com/sabbah13/newo-cli/compare/v3.7.1...v3.7.2
 [3.7.1]: https://github.com/sabbah13/newo-cli/compare/v3.7.0...v3.7.1
 [3.3.0]: https://github.com/sabbah13/newo-cli/compare/v3.2.0...v3.3.0
 [3.2.0]: https://github.com/sabbah13/newo-cli/compare/v3.1.0...v3.2.0

package/README.md

@@ -8,6 +8,9 @@
 **NEWO CLI** - Professional command-line tool for NEWO AI Agent development. Features **modular architecture**, **IDN-based file management**, and **comprehensive multi-customer support**.
 
 Sync NEWO "Project → Agent → Flow → Skills" structure to local files with:
+- 🆕 **V2 skill creation on push** (v3.7.4) - adding a skill inline to a `newo_v2` `{FlowIdn}.yaml` and pushing now creates it on the platform (previously only updates of existing skills worked)
+- 🆕 **Canvas blank-screen hardening** (v3.7.3) - JSON-typed attributes (e.g. Workflow Builder canvas) with Markdown `\_` escapes or structural newlines no longer corrupt the canvas on push ([#7](https://github.com/sabbah13/newo-cli/pull/7))
+- 🆕 **Flow metadata sync** (v3.7.2) - `newo push` now reconciles flow title, events, and state_fields from local `metadata.yaml` to the platform (closes [#3](https://github.com/sabbah13/newo-cli/issues/3))
 - 🆕 **Dual format support** (v3.6.0) - `cli_v1` (native) and `newo_v2` (platform compatible), auto-detected per customer
 - 🆕 **Libraries** (v3.6.0) - Pull/push shared reusable skills across agents within a project
 - 🆕 **Bulk export** (v3.6.0) - `newo export` downloads complete V2 ZIP from platform
@@ -153,6 +156,28 @@ NEWO_REFRESH_URL=custom_refresh_endpoint   # Custom refresh endpoint
 | `newo import-akb` | Import knowledge base articles | • Structured text parsing<br>• Bulk article import<br>• Validation and error reporting |
 | `newo meta` | Get project metadata (debug) | • Project structure analysis<br>• Metadata validation |
 
+### Flow Metadata Sync (NEW v3.7.2)
+
+`newo push` now reconciles **flow-level metadata** — title, `events:`, and `state_fields:` — from local YAML to the platform. Before v3.7.2 push only uploaded skill scripts, so edits to a flow's `metadata.yaml` (V1) or `{FlowIdn}.yaml` (V2) silently never reached the platform; events added via `newo create-event` could appear to disappear after a pull → push cycle. Closes [#3](https://github.com/sabbah13/newo-cli/issues/3).
+
+**How it works:**
+
+| Local change in `metadata.yaml` | What push does |
+|---|---|
+| `title:` changed | `PATCH /api/v1/designer/flows/{id}` with full descriptor |
+| New event in `events:` | `POST /api/v1/designer/flows/{id}/events` |
+| Event field edited | `PATCH /api/v1/designer/flows/events/{eventId}` |
+| Event removed from list | `DELETE /api/v1/designer/flows/events/{eventId}` |
+| Same for `state_fields:` | Mirrored CRUD against `/states` |
+
+**Safety:**
+
+- **Hash-gated**: flows whose `metadata.yaml` SHA256 is unchanged are *not* compared against the platform. Stale local trees cannot wipe events you created via the Builder UI.
+- **Full sync on changed flows**: when you *do* edit `metadata.yaml`, local becomes the source of truth for that flow. Events present on the platform but missing locally are deleted. To keep events created out-of-band, run `newo pull` before editing.
+- **Push output**: changed flows print `↑ Flow <flow>: events +N/~N/-N, states +N/~N/-N` so you see exactly what synced.
+
+**Available in:** legacy V1 push path (`pushChanged`), `ProjectSyncStrategy`, and `V2ProjectSyncStrategy`. Works the same with `newo push --format cli_v1` and `--format newo_v2`.
+
 ### Lint, Format, Check (NEW v3.7.0)
 
 Static-analysis over DSL files, powered by [`newo-dsl-analyzer`](https://www.npmjs.com/package/newo-dsl-analyzer). Same engine that runs in the VS Code extension - no drift between editor and CI.

package/dist/domain/strategies/sync/V2ProjectSyncStrategy.d.ts

@@ -65,6 +65,39 @@ export declare class V2ProjectSyncStrategy implements ISyncStrategy<ProjectMeta,
      * shared syncFlowMetadata routine that calls PATCH/POST/DELETE per child.
      */
     private pushV2FlowYamlUpdate;
+    /**
+     * Reconcile inline skill definitions from V2 flow YAML before pushing scripts.
+     *
+     * V2 keeps skill metadata (model, runner_type, parameters) in the flow YAML,
+     * not in a separate skill metadata file. The map only contains the remote IDs
+     * from a previous pull, so new local skills must be created before their
+     * callers can be published.
+     */
+    private syncV2FlowYamlDefinitions;
+    private createMissingSkillParameters;
+    /**
+     * Detect "resource already exists" API errors.
+     *
+     * Matches only on the precise phrases the platform actually returns
+     * ("already exists", "duplicate key"). Loose substrings like "exist"
+     * would otherwise sweep up unrelated "does not exist" / "doesn't exist"
+     * errors and trigger an incorrect reuse fallback.
+     */
+    private isAlreadyExistsApiError;
+    private normalizeRunnerType;
+    private normalizeParameters;
+    /**
+     * Fail fast if no model could be resolved for a V2 skill.
+     *
+     * `buildV2SkillMetadataFromYaml` falls back to empty strings when neither
+     * the skill nor the flow declare a model. The platform rejects empty
+     * model_idn/provider_idn at creation/update time, but the error it returns
+     * is generic — we surface a clearer message before issuing the request.
+     */
+    private assertSkillModelResolved;
+    private buildV2SkillMetadataFromYaml;
+    private skillMetadataDiffers;
+    private resolveV2FlowSkillScriptPath;
     /**
      * Push a V2 skill update
      *
@@ -81,6 +114,7 @@ export declare class V2ProjectSyncStrategy implements ISyncStrategy<ProjectMeta,
      */
     private publishAllFlows;
     getChanges(customer: CustomerConfig): Promise<ChangeItem<LocalProjectData>[]>;
+    private loadLocalV2FlowSkills;
     validate(customer: CustomerConfig, _items: LocalProjectData[]): Promise<ValidationResult>;
     getStatus(customer: CustomerConfig): Promise<StatusSummary>;
 }

package/dist/domain/strategies/sync/V2ProjectSyncStrategy.js

@@ -14,13 +14,13 @@
  *           skills/{SkillIdn}.nsl|.nslg
  */
 import fs from 'fs-extra';
-import { listProjects, listAgents, listFlowSkills, listFlowEvents, listFlowStates, updateSkill, publishFlow, getProjectAttributes, getCustomerAttributes, listLibraries, updateLibrarySkill, getFlow, } from '../../../api.js';
+import { listProjects, listAgents, listFlowSkills, listFlowEvents, listFlowStates, createSkill, createSkillParameter, updateSkill, publishFlow, getProjectAttributes, getCustomerAttributes, listLibraries, updateLibrarySkill, getFlow, } from '../../../api.js';
 import { syncFlowMetadata, emptyFlowSyncCounts, totalFlowSyncOps, describeFlowSyncCounts } from '../../../sync/flow-metadata.js';
 import { ensureStateOnly, writeFileSafe, mapPath, } from '../../../fsutil.js';
 import { sha256, saveHashes, loadHashes } from '../../../hash.js';
-import { v2ImportVersionPath, v2ProjectYamlPath, v2AgentYamlPath, v2FlowYamlPath, v2SkillScriptPath, v2SkillRelativePath, v2ProjectAttributesPath, v2CustomerAttributesPath, v2AkbDir, v2AkbPath, v2LibraryYamlPath, v2LibrarySkillScriptPath, v2LibrarySkillRelativePath, } from '../../../format/paths-v2.js';
+import { v2ImportVersionPath, v2ProjectYamlPath, v2AgentDir, v2AgentYamlPath, v2FlowYamlPath, v2SkillScriptPath, v2SkillRelativePath, v2ProjectAttributesPath, v2CustomerAttributesPath, v2AkbDir, v2AkbPath, v2LibraryYamlPath, v2LibrarySkillScriptPath, v2LibrarySkillRelativePath, } from '../../../format/paths-v2.js';
 import { V2_IMPORT_VERSION, } from '../../../format/types.js';
-import { generateV2FlowYaml, generateV2ProjectYaml, generateV2AgentYaml, buildV2InlineSkill, buildV2FlowEvent, buildV2StateField, parseV2FlowYaml, } from '../../../format/v2-yaml.js';
+import { generateV2FlowYaml, generateV2ProjectYaml, generateV2AgentYaml, parseV2FlowYaml, buildV2InlineSkill, buildV2FlowEvent, buildV2StateField, } from '../../../format/v2-yaml.js';
 import { isContentDifferent } from '../../../sync/skill-files.js';
 import yaml from 'js-yaml';
 import { patchYamlToPyyaml } from '../../../format/yaml-patch.js';
@@ -438,8 +438,15 @@ export class V2ProjectSyncStrategy {
             return result;
         }
         const mapData = await fs.readJson(mapFile);
+        const metadataSync = await this.syncV2FlowYamlDefinitions(client, customer, mapData, newHashes);
+        result.created += metadataSync.created;
+        result.updated += metadataSync.updated;
+        result.errors.push(...metadataSync.errors);
         for (const change of changes) {
             try {
+                if (metadataSync.syncedPaths.has(change.path)) {
+                    continue;
+                }
                 if (change.operation === 'modified') {
                     // V2 flow YAML: newo_customers/{cust}/{proj}/agents/{agent}/flows/{flow}/{flow}.yaml
                     // The flow YAML carries title, events, and state_fields inline, so
@@ -461,6 +468,9 @@ export class V2ProjectSyncStrategy {
                 result.errors.push(`Failed to push ${change.path}: ${error instanceof Error ? error.message : String(error)}`);
             }
         }
+        if (metadataSync.created > 0 || metadataSync.updated > 0) {
+            await writeFileSafe(mapFile, JSON.stringify(mapData, null, 2));
+        }
         await saveHashes(newHashes, customer.idn);
         if (result.created > 0 || result.updated > 0) {
             await this.publishAllFlows(client, mapData);
@@ -564,6 +574,245 @@ export class V2ProjectSyncStrategy {
         newHashes[change.path] = sha256(content);
         return total;
     }
+    /**
+     * Reconcile inline skill definitions from V2 flow YAML before pushing scripts.
+     *
+     * V2 keeps skill metadata (model, runner_type, parameters) in the flow YAML,
+     * not in a separate skill metadata file. The map only contains the remote IDs
+     * from a previous pull, so new local skills must be created before their
+     * callers can be published.
+     */
+    async syncV2FlowYamlDefinitions(client, customer, mapData, newHashes) {
+        let created = 0;
+        let updated = 0;
+        const syncedPaths = new Set();
+        const errors = [];
+        for (const [projectIdn, projectData] of Object.entries(mapData.projects)) {
+            for (const [agentIdn, agentData] of Object.entries(projectData.agents)) {
+                for (const [flowIdn, flowData] of Object.entries(agentData.flows)) {
+                    const flowYamlPath = v2FlowYamlPath(customer.idn, projectIdn, agentIdn, flowIdn);
+                    if (!(await fs.pathExists(flowYamlPath))) {
+                        continue;
+                    }
+                    let flowDef;
+                    try {
+                        flowDef = await parseV2FlowYaml(flowYamlPath);
+                    }
+                    catch (error) {
+                        this.logger.warn(`[newo_v2] Failed to parse flow YAML ${flowYamlPath}: ${error instanceof Error ? error.message : String(error)}`);
+                        continue;
+                    }
+                    for (const skill of flowDef.skills || []) {
+                        const skillLocator = `${projectIdn}/${agentIdn}/${flowIdn}/${skill.idn}`;
+                        // Per-skill failure isolation: one broken skill must not abort the
+                        // push of every other project/flow in the workspace.
+                        try {
+                            const runnerType = this.normalizeRunnerType(skill.runner_type);
+                            const scriptPath = await this.resolveV2FlowSkillScriptPath(customer.idn, projectIdn, agentIdn, flowIdn, skill.idn, runnerType, skill.prompt_script);
+                            if (!(await fs.pathExists(scriptPath))) {
+                                errors.push(`[newo_v2] Missing script for skill ${skillLocator}: ${scriptPath}`);
+                                continue;
+                            }
+                            const content = await fs.readFile(scriptPath, 'utf8');
+                            const localMetadata = this.buildV2SkillMetadataFromYaml(skill, flowDef, runnerType, flowData.skills[skill.idn]);
+                            const existingSkill = flowData.skills[skill.idn];
+                            if (!existingSkill) {
+                                this.assertSkillModelResolved(localMetadata, skillLocator);
+                                try {
+                                    const createdSkill = await createSkill(client, flowData.id, {
+                                        idn: localMetadata.idn,
+                                        title: localMetadata.title,
+                                        prompt_script: content,
+                                        runner_type: localMetadata.runner_type,
+                                        model: localMetadata.model,
+                                        parameters: localMetadata.parameters,
+                                        path: localMetadata.path || ''
+                                    });
+                                    // The create endpoint ignores inline `parameters` (verified
+                                    // against the live platform) — create them explicitly.
+                                    await this.createMissingSkillParameters(client, { ...localMetadata, id: createdSkill.id, parameters: [] }, localMetadata);
+                                    flowData.skills[skill.idn] = {
+                                        ...localMetadata,
+                                        id: createdSkill.id
+                                    };
+                                    newHashes[scriptPath] = sha256(content);
+                                    syncedPaths.add(scriptPath);
+                                    created++;
+                                    this.logger.info(`[newo_v2] Created skill: ${flowIdn}/${skill.idn}`);
+                                }
+                                catch (error) {
+                                    if (!this.isAlreadyExistsApiError(error)) {
+                                        throw error;
+                                    }
+                                    const remoteSkills = await listFlowSkills(client, flowData.id);
+                                    const remoteSkill = remoteSkills.find(s => s.idn === skill.idn);
+                                    if (!remoteSkill) {
+                                        throw error;
+                                    }
+                                    const remoteMetadata = {
+                                        id: remoteSkill.id,
+                                        idn: remoteSkill.idn,
+                                        title: remoteSkill.title,
+                                        runner_type: remoteSkill.runner_type,
+                                        model: remoteSkill.model,
+                                        parameters: this.normalizeParameters(remoteSkill.parameters),
+                                        path: remoteSkill.path
+                                    };
+                                    await this.createMissingSkillParameters(client, remoteMetadata, localMetadata);
+                                    await updateSkill(client, {
+                                        id: remoteSkill.id,
+                                        title: localMetadata.title,
+                                        idn: localMetadata.idn,
+                                        prompt_script: content,
+                                        runner_type: localMetadata.runner_type,
+                                        model: localMetadata.model,
+                                        parameters: localMetadata.parameters,
+                                        path: remoteSkill.path || localMetadata.path
+                                    });
+                                    flowData.skills[skill.idn] = {
+                                        ...localMetadata,
+                                        id: remoteSkill.id,
+                                        path: remoteSkill.path || localMetadata.path
+                                    };
+                                    newHashes[scriptPath] = sha256(content);
+                                    syncedPaths.add(scriptPath);
+                                    updated++;
+                                    this.logger.info(`[newo_v2] Reused existing skill: ${flowIdn}/${skill.idn}`);
+                                }
+                                continue;
+                            }
+                            const createdParameters = await this.createMissingSkillParameters(client, existingSkill, localMetadata);
+                            if (createdParameters > 0 || this.skillMetadataDiffers(existingSkill, localMetadata)) {
+                                this.assertSkillModelResolved(localMetadata, skillLocator);
+                                await updateSkill(client, {
+                                    id: existingSkill.id,
+                                    title: localMetadata.title,
+                                    idn: localMetadata.idn,
+                                    prompt_script: content,
+                                    runner_type: localMetadata.runner_type,
+                                    model: localMetadata.model,
+                                    parameters: localMetadata.parameters,
+                                    path: localMetadata.path
+                                });
+                                flowData.skills[skill.idn] = {
+                                    ...localMetadata,
+                                    id: existingSkill.id
+                                };
+                                newHashes[scriptPath] = sha256(content);
+                                syncedPaths.add(scriptPath);
+                                updated++;
+                                this.logger.info(`[newo_v2] Updated skill metadata: ${flowIdn}/${skill.idn}`);
+                            }
+                        }
+                        catch (error) {
+                            errors.push(`Failed to sync skill ${skillLocator}: ${error instanceof Error ? error.message : String(error)}`);
+                        }
+                    }
+                }
+            }
+        }
+        return { created, updated, syncedPaths, errors };
+    }
+    async createMissingSkillParameters(client, existing, local) {
+        const existingNames = new Set(this.normalizeParameters(existing.parameters).map(p => p.name));
+        let created = 0;
+        for (const parameter of local.parameters) {
+            if (existingNames.has(parameter.name)) {
+                continue;
+            }
+            try {
+                await createSkillParameter(client, existing.id, {
+                    name: parameter.name,
+                    default_value: parameter.default_value ?? ''
+                });
+                created++;
+                this.logger.info(`[newo_v2] Created skill parameter: ${local.idn}/${parameter.name}`);
+            }
+            catch (error) {
+                if (!this.isAlreadyExistsApiError(error)) {
+                    throw error;
+                }
+            }
+            existingNames.add(parameter.name);
+        }
+        return created;
+    }
+    /**
+     * Detect "resource already exists" API errors.
+     *
+     * Matches only on the precise phrases the platform actually returns
+     * ("already exists", "duplicate key"). Loose substrings like "exist"
+     * would otherwise sweep up unrelated "does not exist" / "doesn't exist"
+     * errors and trigger an incorrect reuse fallback.
+     */
+    isAlreadyExistsApiError(error) {
+        const response = error?.response;
+        const status = response?.status;
+        if (status !== 400 && status !== 409 && status !== 422) {
+            return false;
+        }
+        const haystack = JSON.stringify(response?.data ?? (error instanceof Error ? error.message : String(error))).toLowerCase();
+        return haystack.includes('already exists') || haystack.includes('duplicate key');
+    }
+    normalizeRunnerType(runnerType) {
+        return runnerType === 'nsl' ? 'nsl' : 'guidance';
+    }
+    normalizeParameters(parameters) {
+        return (parameters || []).map(p => ({
+            name: p.name,
+            default_value: p.default_value ?? ''
+        }));
+    }
+    /**
+     * Fail fast if no model could be resolved for a V2 skill.
+     *
+     * `buildV2SkillMetadataFromYaml` falls back to empty strings when neither
+     * the skill nor the flow declare a model. The platform rejects empty
+     * model_idn/provider_idn at creation/update time, but the error it returns
+     * is generic — we surface a clearer message before issuing the request.
+     */
+    assertSkillModelResolved(metadata, locator) {
+        if (!metadata.model.model_idn || !metadata.model.provider_idn) {
+            throw new Error(`[newo_v2] Cannot resolve model for skill ${locator}: ` +
+                `model_idn="${metadata.model.model_idn}", provider_idn="${metadata.model.provider_idn}". ` +
+                `Set either skill.model.* or flow default_model_idn/default_provider_idn in the flow YAML.`);
+        }
+    }
+    buildV2SkillMetadataFromYaml(skill, flowDef, runnerType, existing) {
+        return {
+            id: existing?.id || '',
+            idn: skill.idn,
+            title: skill.title || '',
+            runner_type: runnerType,
+            model: {
+                model_idn: skill.model?.model_idn || flowDef.default_model_idn || '',
+                provider_idn: skill.model?.provider_idn || flowDef.default_provider_idn || ''
+            },
+            parameters: this.normalizeParameters(skill.parameters),
+            path: existing?.path || ''
+        };
+    }
+    skillMetadataDiffers(existing, local) {
+        // Compare model/parameters field-by-field, never via JSON.stringify of the
+        // raw objects: the map stores model keys in platform API order
+        // (provider_idn first) while YAML-built metadata uses model_idn first, and
+        // a key-order-sensitive comparison flags every skill as changed.
+        const paramsKey = (params) => JSON.stringify(this.normalizeParameters(params).sort((a, b) => a.name.localeCompare(b.name)));
+        return (existing.title !== local.title ||
+            existing.runner_type !== local.runner_type ||
+            existing.model.model_idn !== local.model.model_idn ||
+            existing.model.provider_idn !== local.model.provider_idn ||
+            paramsKey(existing.parameters) !== paramsKey(local.parameters));
+    }
+    async resolveV2FlowSkillScriptPath(customerIdn, projectIdn, agentIdn, flowIdn, skillIdn, runnerType, promptScript) {
+        if (promptScript) {
+            const fromPromptScript = `${v2AgentDir(customerIdn, projectIdn, agentIdn)}/${promptScript}`;
+            if (await fs.pathExists(fromPromptScript)) {
+                return fromPromptScript;
+            }
+        }
+        return v2SkillScriptPath(customerIdn, projectIdn, agentIdn, flowIdn, skillIdn, runnerType);
+    }
     /**
      * Push a V2 skill update
      *
@@ -686,8 +935,18 @@ export class V2ProjectSyncStrategy {
                     }
                 }
                 for (const [flowIdn, flowData] of Object.entries(agentData.flows)) {
-                    for (const [skillIdn, skillMeta] of Object.entries(flowData.skills)) {
-                        const scriptPath = v2SkillScriptPath(customer.idn, projectIdn, agentIdn, flowIdn, skillIdn, skillMeta.runner_type);
+                    const flowYamlSkills = await this.loadLocalV2FlowSkills(customer.idn, projectIdn, agentIdn, flowIdn);
+                    const skillIdns = new Set([
+                        ...Object.keys(flowData.skills),
+                        ...flowYamlSkills.keys()
+                    ]);
+                    for (const skillIdn of skillIdns) {
+                        const yamlSkill = flowYamlSkills.get(skillIdn);
+                        const skillMeta = flowData.skills[skillIdn];
+                        const runnerType = this.normalizeRunnerType(yamlSkill?.runner_type || skillMeta?.runner_type);
+                        const scriptPath = yamlSkill
+                            ? await this.resolveV2FlowSkillScriptPath(customer.idn, projectIdn, agentIdn, flowIdn, skillIdn, runnerType, yamlSkill.prompt_script)
+                            : v2SkillScriptPath(customer.idn, projectIdn, agentIdn, flowIdn, skillIdn, runnerType);
                         if (await fs.pathExists(scriptPath)) {
                             const content = await fs.readFile(scriptPath, 'utf8');
                             const currentHash = sha256(content);
@@ -726,6 +985,19 @@ export class V2ProjectSyncStrategy {
         }
         return changes;
     }
+    async loadLocalV2FlowSkills(customerIdn, projectIdn, agentIdn, flowIdn) {
+        const flowYamlPath = v2FlowYamlPath(customerIdn, projectIdn, agentIdn, flowIdn);
+        if (!(await fs.pathExists(flowYamlPath))) {
+            return new Map();
+        }
+        try {
+            const flowDef = await parseV2FlowYaml(flowYamlPath);
+            return new Map((flowDef.skills || []).map(skill => [skill.idn, skill]));
+        }
+        catch {
+            return new Map();
+        }
+    }
     async validate(customer, _items) {
         const errors = [];
         const mapFile = mapPath(customer.idn);
@@ -741,7 +1013,46 @@ export class V2ProjectSyncStrategy {
         for (const [projectIdn, projectData] of Object.entries(mapData.projects)) {
             for (const [agentIdn, agentData] of Object.entries(projectData.agents)) {
                 for (const [flowIdn, flowData] of Object.entries(agentData.flows)) {
+                    const flowYamlPath = v2FlowYamlPath(customer.idn, projectIdn, agentIdn, flowIdn);
+                    let localYamlSkills;
+                    if (await fs.pathExists(flowYamlPath)) {
+                        try {
+                            const flowDef = await parseV2FlowYaml(flowYamlPath);
+                            localYamlSkills = new Map((flowDef.skills || []).map(s => [s.idn, s]));
+                            const skillIdns = new Set([
+                                ...Object.keys(flowData.skills),
+                                ...localYamlSkills.keys()
+                            ]);
+                            for (const skillIdn of skillIdns) {
+                                const localYamlSkill = localYamlSkills.get(skillIdn);
+                                const skillMeta = flowData.skills[skillIdn];
+                                if (!localYamlSkill) {
+                                    errors.push({
+                                        field: `skill.${skillIdn}`,
+                                        message: `Skill exists in project map but is missing from flow YAML: ${flowYamlPath}`,
+                                        path: flowYamlPath
+                                    });
+                                    continue;
+                                }
+                                const runnerType = this.normalizeRunnerType(localYamlSkill.runner_type || skillMeta?.runner_type);
+                                const scriptPath = await this.resolveV2FlowSkillScriptPath(customer.idn, projectIdn, agentIdn, flowIdn, skillIdn, runnerType, localYamlSkill.prompt_script);
+                                if (!(await fs.pathExists(scriptPath))) {
+                                    errors.push({
+                                        field: `skill.${localYamlSkill.idn}`,
+                                        message: `Script file not found: ${scriptPath}`,
+                                        path: scriptPath
+                                    });
+                                }
+                            }
+                        }
+                        catch {
+                            localYamlSkills = undefined;
+                        }
+                    }
                     for (const [skillIdn, skillMeta] of Object.entries(flowData.skills)) {
+                        if (localYamlSkills) {
+                            continue;
+                        }
                         const scriptPath = v2SkillScriptPath(customer.idn, projectIdn, agentIdn, flowIdn, skillIdn, skillMeta.runner_type);
                         if (!(await fs.pathExists(scriptPath))) {
                             errors.push({

package/dist/sync/json-attr-utils.d.ts

@@ -8,7 +8,7 @@
  * `value_type: json`. The API may return the `value` field as either a
  * STRING containing JSON or as an already-parsed OBJECT.
  *
- * Without normalization, two bugs leak through:
+ * Without normalization, several bugs leak through:
  *
  * 1. When the API returns the value as an OBJECT, `yaml.dump` serializes
  *    it as a YAML structure (mappings/sequences). Pushing back then sends
@@ -21,10 +21,25 @@
  *    string vs object representations it triggers spurious pushes that
  *    overwrite the canvas with the wrong shape (Builder shows blank).
  *
- * The fix is conservative: for `value_type: json` only, always coerce the
- * value to a STRING when persisting and when pushing, and use canonical
- * JSON for comparisons. String-typed values in the wild are left
- * untouched, so no churn for the majority of attributes.
+ * 3. (Bug 3.7.2-a) Canvas JSON strings with structural newlines (real
+ *    U+000A between tokens) can be emitted by yaml.dump as double-quoted
+ *    scalars with `\n` escape sequences. patchYamlToPyyaml then converts
+ *    those to single-quoted YAML scalars, where `\n` is treated as two
+ *    literal chars (backslash + n). On push the platform stores those
+ *    literal chars and the Builder calls JSON.parse, which fails on
+ *    backslash-n as structural whitespace.
+ *
+ * 4. (Bug 3.7.2-b) Canvas body text contains Markdown with `\_`
+ *    (backslash + underscore). `\_` is not a valid JSON escape sequence
+ *    per RFC 8259 (valid ones: " \ / b f n r t uXXXX). Chrome V8's
+ *    JSON.parse is strict: it throws SyntaxError on `\_`, silently
+ *    blanking the Builder.
+ *
+ * The fix for (3) and (4): for `value_type: json` string values, strip
+ * invalid escape sequences then compact via JSON.parse + JSON.stringify.
+ * Compaction removes structural newlines and re-serializes all string
+ * values with only valid JSON escapes, producing a single-line string
+ * that round-trips through YAML without corruption.
  */
 /**
  * True if the attribute is a JSON-typed attribute (case- and
@@ -32,26 +47,40 @@
  * `ValueType.JSON`, etc.).
  */
 export declare function isJsonValueType(valueType: unknown): boolean;
+/**
+ * Fix invalid JSON escape sequences inside JSON string values.
+ *
+ * Per RFC 8259, valid escape sequences inside a JSON string are:
+ *   \" \\ \/ \b \f \n \r \t \uXXXX
+ * Anything else (e.g. `\_` `\.` from Markdown) is invalid and causes
+ * JSON.parse to throw. Fix: drop the backslash (e.g. `\_` → `_`).
+ *
+ * Only modifies characters inside JSON string values (tracks quote
+ * context). Structural characters outside strings are untouched.
+ */
+export declare function fixInvalidJsonEscapes(s: string): string;
 /**
  * Coerce a JSON-typed attribute's value to a STRING suitable for storage
  * in attributes.yaml and for sending to the platform.
  *
  * - `null` / `undefined` → `''`
  * - object → compact JSON string (`JSON.stringify(value)`)
- * - string → returned as-is (we trust the platform's existing format)
+ * - string → fix invalid escapes (e.g. `\_` → `_`), then compact via
+ *            JSON.parse + JSON.stringify. If parsing still fails after
+ *            fixing escapes, return the fixed string as-is.
  * - other → `String(value)`
  *
- * We deliberately do NOT re-format string values, even when they look
- * like JSON. Many existing canvases are stored pretty-printed and
- * reformatting would create huge spurious diffs in users' repos.
+ * Compacting removes structural newlines and guarantees a single-line
+ * string that yaml.dump serializes without escape-sequence corruption in
+ * the patchYamlToPyyaml pass. See module-level comment for full context.
  */
 export declare function normalizeJsonValueForStorage(value: unknown): string;
 /**
  * Canonical comparison for JSON-typed attribute values.
  *
  * Returns the canonical form (compact JSON if parseable, otherwise the
- * raw string). Use this on both sides of a comparison so that pretty- vs
- * compact-printed JSON does not register as a change, and so that an
+ * fixed string). Use this on both sides of a comparison so that pretty-
+ * vs compact-printed JSON does not register as a change, and so that an
  * object on one side equals its stringified form on the other side.
  */
 export declare function canonicalJsonValue(value: unknown): string;