create-principles-disciple 1.95.0 → 1.96.0

package/console/dist/server/config/pd-config-store.js

@@ -693,29 +693,66 @@ export function updateFeatureFlag(workspaceDir, featureName, enabled) {
     else {
         rawConfig = {};
     }
-    // 4. Refuse to CREATE a features section if absent (spec §13.4: 不允许新增)
-    //    Use Object.hasOwn for untrusted key check (ERR-013)
-    if (!Object.hasOwn(rawConfig, 'features') || !isRecord(rawConfig.features)) {
+    // 4. PRI-477 onboarding: auto-create `features:` section ONLY when absent.
+    //    Original spec §13.4 "不允许新增" applied to UNREGISTERED flags —
+    //    auto-creating the section for registered flags (validated in step 1) is
+    //    safe and required for the FlagToggleCard one-click enable flow on fresh
+    //    installs where .pd/config.yaml has no features: section yet.
+    //
+    //    IMPORTANT — Runtime Contract `rc-9-no-silent-fallback` (ERR-002):
+    //    If `features` EXISTS but is NOT a record/object, we must NOT silently
+    //    overwrite the user's malformed value with defaults — that would hide a
+    //    config error and lose the original mistake. Return 409 conflict so the
+    //    Owner can fix the config first. Without this guard, a config typo like
+    //    `features: "oops"` would be silently reset on the first flag toggle.
+    //
+    //    Use Object.hasOwn for untrusted key check (ERR-013).
+    let featuresSection;
+    if (!Object.hasOwn(rawConfig, 'features')) {
+        // Section absent — seed with defaults from the registered flag set so the
+        // subsequent validatePdConfig passes (it requires prompt/code_tool_hook /
+        // defer_archive as registered flags). Computed once at module load.
+        featuresSection = {};
+        for (const [flagId, flag] of Object.entries(_DEFAULT_FLAGS_RESULT.flags)) {
+            featuresSection[flagId] = { category: flag.category, enabled: flag.enabled };
+        }
+        rawConfig.features = featuresSection;
+    }
+    else if (isRecord(rawConfig.features)) {
+        featuresSection = rawConfig.features;
+    }
+    else {
+        // features: exists but is malformed (string, array, number, null, etc.).
+        // Reject rather than silently resetting — rc-9-no-silent-fallback.
+        const gotType = rawConfig.features === null ? 'null' : typeof rawConfig.features;
         return {
             ok: false,
-            statusCode: 422,
-            error: 'no_features_section',
-            message: `Cannot update feature flag: .pd/config.yaml has no 'features:' section. This API does not create new feature sections.`,
-            nextAction: 'Manually add a features: section to .pd/config.yaml first, or set the flag via yaml directly.',
+            statusCode: 409,
+            error: 'conflict',
+            message: `Cannot update feature flag: .pd/config.yaml has a 'features:' section that ` +
+                `is not an object/map (got ${gotType}). Fix the config file so 'features:' ` +
+                `is a map of flag objects before retrying, or remove the 'features:' key ` +
+                `entirely so PD can seed registered-flag defaults.`,
+            nextAction: "Open .pd/config.yaml and set 'features: {}' (or remove the 'features:' line).",
         };
     }
-    // 5. Load existing config — if malformed, refuse to write
-    const loadResult = loadPdConfig(workspaceDir);
-    if (!loadResult.ok) {
+    // 5. Validate the in-memory rawConfig (with auto-created features section).
+    //    NOTE: We do NOT call loadPdConfig(workspaceDir) here because that reads
+    //    from DISK, where the features section may still be missing (the exact
+    //    case we just auto-created for). Validating rawConfig in memory gives
+    //    the same malformed-config protection without the false-positive on
+    //    fresh installs. PRI-477.
+    const existingConfigValidation = validatePdConfig(rawConfig);
+    if (!existingConfigValidation.ok) {
         return {
             ok: false,
             statusCode: 409,
             error: 'conflict',
-            message: `Cannot update feature flag: existing .pd/config.yaml is malformed. Fix config errors first. Errors: ${loadResult.errors.map(e => e.reason).join('; ')}`,
+            message: `Cannot update feature flag: existing .pd/config.yaml is malformed. Fix config errors first. Errors: ${existingConfigValidation.errors.map(e => e.reason).join('; ')}`,
         };
     }
     // 6. Merge: update features[featureName].enabled, preserving other flags
-    const existingFeatures = { ...rawConfig.features };
+    const existingFeatures = { ...featuresSection };
     const existingEntry = Object.hasOwn(existingFeatures, featureName)
         ? existingFeatures[featureName]
         : undefined;

package/console/dist/server/index.js

@@ -328,9 +328,10 @@ function handleRequest(services) {
                 asyncHandler(() => handleGovernanceRoute(req, res, services.workspaceDir))(req, res);
                 return;
             }
-            // PRI-466: GET /api/v1/intent
-            if (urlPath === '/api/v1/intent') {
-                asyncHandler(() => handleIntentRoute(req, res, services.workspaceDir))(req, res);
+            // PRI-466/477: GET/POST/PUT /api/v1/intent (+ /init, /content sub-paths)
+            if (urlPath === '/api/v1/intent' || urlPath.startsWith('/api/v1/intent/')) {
+                const subPath = urlPath === '/api/v1/intent' ? '' : urlPath.slice('/api/v1/intent'.length);
+                asyncHandler(() => handleIntentRoute(req, res, { workspaceDir: services.workspaceDir, subPath }))(req, res);
                 return;
             }
             // PRI-470: IntentDecisionRecord (POST/GET /api/v1/intent-decisions, /:id, /summary)

package/console/dist/server/models/IntentPageModel.d.ts

@@ -1,4 +1,4 @@
-import { type IntentDocWarning } from '@principles/core/runtime-v2';
+import { type IntentDocWarning, type IntentDocVersion, type IntentLang } from '@principles/core/runtime-v2';
 export interface IntentPageResult {
     ok: boolean;
     found: boolean;
@@ -11,8 +11,42 @@ export interface IntentPageResult {
     reason?: string;
     nextAction?: string;
 }
+export interface IntentInitResult {
+    ok: boolean;
+    created: boolean;
+    path?: string;
+    reason?: string;
+    nextAction?: string;
+}
+export interface IntentSaveResult {
+    ok: boolean;
+    saved: boolean;
+    path?: string;
+    contentHash?: string;
+    lastEditedAt?: string;
+    warnings?: IntentDocWarning[];
+    reason?: string;
+    nextAction?: string;
+}
+export interface IntentRawContentResult {
+    ok: boolean;
+    content?: string;
+    path?: string;
+    reason?: string;
+    nextAction?: string;
+}
+export interface IntentVersionResult {
+    ok: boolean;
+    versions?: IntentDocVersion[];
+    reason?: string;
+    nextAction?: string;
+}
 export declare class IntentPageModel {
     private readonly workspaceDir;
     constructor(workspaceDir: string);
-    getSummary(flagEnabled: boolean): Promise<IntentPageResult>;
+    getSummary(flagEnabled: boolean, lang: IntentLang): Promise<IntentPageResult>;
+    getRawContent(flagEnabled: boolean, lang: IntentLang): Promise<IntentRawContentResult>;
+    createTemplate(flagEnabled: boolean, force: boolean, lang: IntentLang): Promise<IntentInitResult>;
+    saveContent(flagEnabled: boolean, content: unknown, lang: IntentLang): Promise<IntentSaveResult>;
+    getVersions(lang: IntentLang): Promise<IntentVersionResult>;
 }

package/console/dist/server/models/IntentPageModel.js

@@ -1,14 +1,40 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import { INTENT_MAX_BYTES, parseIntentDocSections, computeIntentContentHash, validateIntentDocSections, } from '@principles/core/runtime-v2';
-const INTENT_FILENAME = 'INTENT.md';
+import { INTENT_MAX_BYTES, getIntentFilename, createIntentTemplate, parseIntentDocSections, computeIntentContentHash, validateIntentDocSections, SqliteConnection, SqliteIntentDocVersionStore, } from '@principles/core/runtime-v2';
 const INTENT_DIR = '.principles';
+function stateDbExists(workspaceDir) {
+    return fs.existsSync(path.join(workspaceDir, '.pd', 'state.db'));
+}
+/** Best-effort version record — never blocks save on failure. */
+function recordVersion(args) {
+    // Note: no stateDbExists short-circuit. SqliteConnection creates the .pd
+    // dir and state.db file (with intent_doc_versions table via CREATE TABLE
+    // IF NOT EXISTS) on first open. Short-circuiting here would silently drop
+    // the first-write version history on fresh workspaces — the operator
+    // would see an empty history panel after their very first save.
+    try {
+        const connection = new SqliteConnection({ workspaceDir: args.workspaceDir });
+        try {
+            const store = new SqliteIntentDocVersionStore(connection);
+            store.saveVersion({ lang: args.lang, content: args.content, reason: args.reason });
+        }
+        finally {
+            try {
+                connection.close();
+            }
+            catch { /* best-effort */ }
+        }
+    }
+    catch {
+        // Version recording is best-effort — never block save on failure.
+    }
+}
 export class IntentPageModel {
     workspaceDir;
     constructor(workspaceDir) {
         this.workspaceDir = workspaceDir;
     }
-    async getSummary(flagEnabled) {
+    async getSummary(flagEnabled, lang) {
         if (!flagEnabled) {
             return {
                 ok: false,
@@ -16,10 +42,10 @@ export class IntentPageModel {
                 flagEnabled: false,
                 warnings: [],
                 reason: 'flag_disabled',
-                nextAction: 'Enable the intent_engineering feature flag in .pd/config.yaml to read INTENT.md.',
+                nextAction: `Enable the intent_engineering feature flag in .pd/config.yaml to read ${getIntentFilename(lang)}.`,
             };
         }
-        const filePath = path.join(this.workspaceDir, INTENT_DIR, INTENT_FILENAME);
+        const filePath = path.join(this.workspaceDir, INTENT_DIR, getIntentFilename(lang));
         try {
             if (!fs.existsSync(filePath)) {
                 return {
@@ -28,7 +54,7 @@ export class IntentPageModel {
                     flagEnabled: true,
                     warnings: [],
                     reason: 'not_found',
-                    nextAction: 'Create .principles/INTENT.md using "pd intent init".',
+                    nextAction: `Create .principles/${getIntentFilename(lang)} using "pd intent init".`,
                 };
             }
             const stat = fs.statSync(filePath);
@@ -39,7 +65,7 @@ export class IntentPageModel {
                     flagEnabled: true,
                     warnings: [],
                     reason: 'oversized',
-                    nextAction: `INTENT.md exceeds ${INTENT_MAX_BYTES} bytes (${stat.size} bytes). Reduce content.`,
+                    nextAction: `${getIntentFilename(lang)} exceeds ${INTENT_MAX_BYTES} bytes (${stat.size} bytes). Reduce content.`,
                 };
             }
             const raw = fs.readFileSync(filePath, 'utf8');
@@ -74,16 +100,192 @@ export class IntentPageModel {
             };
         }
         catch (err) {
-            // Runtime Contract Rule #9: log underlying error for observability
-            // while preserving the never-throws contract.
-            console.error('[IntentPageModel] failed to read INTENT.md:', err);
+            console.error(`[IntentPageModel] failed to read ${getIntentFilename(lang)}:`, err);
             return {
                 ok: false,
                 found: false,
                 flagEnabled: true,
                 warnings: [],
                 reason: 'read_error',
-                nextAction: 'Check filesystem permissions for .principles/INTENT.md.',
+                nextAction: `Check filesystem permissions for .principles/${getIntentFilename(lang)}.`,
+            };
+        }
+    }
+    async getRawContent(flagEnabled, lang) {
+        if (!flagEnabled) {
+            return {
+                ok: false,
+                reason: 'flag_disabled',
+                nextAction: 'Enable the intent_engineering feature flag first.',
+            };
+        }
+        const filePath = path.join(this.workspaceDir, INTENT_DIR, getIntentFilename(lang));
+        try {
+            if (!fs.existsSync(filePath)) {
+                return {
+                    ok: false,
+                    reason: 'not_found',
+                    nextAction: `${getIntentFilename(lang)} does not exist. Create it first using POST /api/v1/intent/init.`,
+                };
+            }
+            const stat = fs.statSync(filePath);
+            if (stat.size > INTENT_MAX_BYTES) {
+                return {
+                    ok: false,
+                    reason: 'oversized',
+                    nextAction: `${getIntentFilename(lang)} exceeds ${INTENT_MAX_BYTES} bytes (${stat.size} bytes). Reduce content before opening the editor.`,
+                };
+            }
+            const content = fs.readFileSync(filePath, 'utf8');
+            return { ok: true, content, path: filePath };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            console.error(`[IntentPageModel] failed to read raw ${getIntentFilename(lang)}:`, err);
+            return {
+                ok: false,
+                reason: 'read_error',
+                nextAction: `Could not read ${getIntentFilename(lang)}: ${message}. Check filesystem permissions.`,
+            };
+        }
+    }
+    async createTemplate(flagEnabled, force, lang) {
+        if (!flagEnabled) {
+            return {
+                ok: false,
+                created: false,
+                reason: 'flag_disabled',
+                nextAction: 'Enable the intent_engineering feature flag first.',
+            };
+        }
+        const dirPath = path.join(this.workspaceDir, INTENT_DIR);
+        const filePath = path.join(dirPath, getIntentFilename(lang));
+        try {
+            if (!fs.existsSync(dirPath)) {
+                fs.mkdirSync(dirPath, { recursive: true });
+            }
+            if (fs.existsSync(filePath) && !force) {
+                return {
+                    ok: true,
+                    created: false,
+                    path: filePath,
+                    reason: 'already_exists',
+                    nextAction: 'Use force=true to overwrite, or edit the existing file instead.',
+                };
+            }
+            const templateContent = createIntentTemplate(lang);
+            fs.writeFileSync(filePath, templateContent, 'utf8');
+            recordVersion({ workspaceDir: this.workspaceDir, lang, content: templateContent, reason: 'init' });
+            return {
+                ok: true,
+                created: true,
+                path: filePath,
+            };
+        }
+        catch (err) {
+            console.error(`[IntentPageModel] failed to create ${getIntentFilename(lang)}:`, err);
+            return {
+                ok: false,
+                created: false,
+                reason: 'write_error',
+                nextAction: 'Check filesystem permissions for .principles/ directory.',
+            };
+        }
+    }
+    async saveContent(flagEnabled, content, lang) {
+        if (!flagEnabled) {
+            return {
+                ok: false,
+                saved: false,
+                reason: 'flag_disabled',
+                nextAction: 'Enable the intent_engineering feature flag first.',
+            };
+        }
+        if (typeof content !== 'string') {
+            return {
+                ok: false,
+                saved: false,
+                reason: 'invalid_content',
+                nextAction: 'Content must be a string.',
+            };
+        }
+        if (content.length === 0) {
+            return {
+                ok: false,
+                saved: false,
+                reason: 'empty_content',
+                nextAction: 'Content cannot be empty.',
+            };
+        }
+        const byteLength = Buffer.byteLength(content, 'utf8');
+        if (byteLength > INTENT_MAX_BYTES) {
+            return {
+                ok: false,
+                saved: false,
+                reason: 'oversized',
+                nextAction: `Content exceeds ${INTENT_MAX_BYTES} bytes (${byteLength} bytes). Reduce content.`,
+            };
+        }
+        const dirPath = path.join(this.workspaceDir, INTENT_DIR);
+        const filePath = path.join(dirPath, getIntentFilename(lang));
+        try {
+            if (!fs.existsSync(dirPath)) {
+                fs.mkdirSync(dirPath, { recursive: true });
+            }
+            fs.writeFileSync(filePath, content, 'utf8');
+            const sections = parseIntentDocSections(content);
+            const warnings = validateIntentDocSections(sections);
+            const contentHash = computeIntentContentHash(content);
+            const stat = fs.statSync(filePath);
+            recordVersion({ workspaceDir: this.workspaceDir, lang, content, reason: 'save' });
+            return {
+                ok: true,
+                saved: true,
+                path: filePath,
+                contentHash,
+                lastEditedAt: stat.mtime.toISOString(),
+                warnings,
+            };
+        }
+        catch (err) {
+            console.error(`[IntentPageModel] failed to save ${getIntentFilename(lang)}:`, err);
+            return {
+                ok: false,
+                saved: false,
+                reason: 'write_error',
+                nextAction: `Check filesystem permissions for .principles/${getIntentFilename(lang)}.`,
+            };
+        }
+    }
+    async getVersions(lang) {
+        if (!stateDbExists(this.workspaceDir)) {
+            return {
+                ok: false,
+                reason: 'state_db_not_found',
+                nextAction: 'Run a PD command that creates state.db first (e.g. pd pain list).',
+            };
+        }
+        try {
+            const connection = new SqliteConnection({ workspaceDir: this.workspaceDir, readonly: true });
+            try {
+                const store = new SqliteIntentDocVersionStore(connection);
+                const versions = await store.listVersions(lang);
+                return { ok: true, versions };
+            }
+            finally {
+                try {
+                    connection.close();
+                }
+                catch { /* best-effort */ }
+            }
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            console.error(`[IntentPageModel] failed to list versions:`, err);
+            return {
+                ok: false,
+                reason: 'read_error',
+                nextAction: `Could not read version history: ${message}`,
             };
         }
     }

package/console/dist/server/routes/intent.d.ts

@@ -1,3 +1,7 @@
 import type { IncomingMessage, ServerResponse } from 'node:http';
-export declare function handleIntentRoute(req: IncomingMessage, res: ServerResponse, workspaceDir: string): Promise<void>;
+export interface IntentRouteContext {
+    workspaceDir: string;
+    subPath: string;
+}
+export declare function handleIntentRoute(req: IncomingMessage, res: ServerResponse, ctx: IntentRouteContext): Promise<void>;
 export declare function disposeIntentModels(): void;

package/console/dist/server/routes/intent.js

@@ -1,6 +1,13 @@
 import { IntentPageModel } from '../models/IntentPageModel.js';
-import { sendSuccess, sendError } from '../utils/response.js';
+import { sendSuccess, sendError, sendJson } from '../utils/response.js';
 import { loadPdConfig, computeFlagsFromLoadResult } from '../config/pd-config-store.js';
+import { readBody } from '../utils/request.js';
+/** Parse lang from query string; default 'zh-CN' if missing/invalid. */
+function parseLang(req) {
+    const url = new URL(req.url ?? '', 'http://localhost');
+    const lang = url.searchParams.get('lang');
+    return lang === 'en' ? 'en' : 'zh-CN';
+}
 const MODEL_CACHE_TTL_MS = 30 * 1000;
 const models = new Map();
 function getModel(workspaceDir) {
@@ -12,18 +19,199 @@ function getModel(workspaceDir) {
     models.set(workspaceDir, { model, cachedAt: Date.now() });
     return model;
 }
-export async function handleIntentRoute(req, res, workspaceDir) {
-    if (req.method !== 'GET') {
-        sendError(res, 405, 'method_not_allowed', 'Only GET method is allowed');
-        return;
-    }
+/** Load the intent_engineering flag state from config. */
+function loadFlagEnabled(workspaceDir) {
+    const configResult = loadPdConfig(workspaceDir);
+    const flagsResult = computeFlagsFromLoadResult(configResult);
+    return flagsResult.flags.intent_engineering?.enabled === true;
+}
+/** Send a structured error with reason + nextAction (Runtime Contract Rule #9). */
+function sendStructuredError(res, payload) {
+    sendError(res, payload.statusCode, payload.error, payload.reason, {
+        reason: payload.reason,
+        nextAction: payload.nextAction,
+    });
+}
+export async function handleIntentRoute(req, res, ctx) {
+    const { workspaceDir, subPath } = ctx;
+    const lang = parseLang(req);
     try {
-        const configResult = loadPdConfig(workspaceDir);
-        const flagsResult = computeFlagsFromLoadResult(configResult);
-        const flagEnabled = flagsResult.flags.intent_engineering?.enabled === true;
-        const model = getModel(workspaceDir);
-        const summary = await model.getSummary(flagEnabled);
-        sendSuccess(res, summary);
+        // ── GET /api/v1/intent — read Intent summary ──────────────────────────
+        if (req.method === 'GET' && subPath === '') {
+            const flagEnabled = loadFlagEnabled(workspaceDir);
+            const model = getModel(workspaceDir);
+            const summary = await model.getSummary(flagEnabled, lang);
+            sendSuccess(res, summary);
+            return;
+        }
+        // ── GET /api/v1/intent/content — read raw INTENT.md for editing ─────────
+        if (req.method === 'GET' && subPath === '/content') {
+            const flagEnabled = loadFlagEnabled(workspaceDir);
+            if (!flagEnabled) {
+                sendStructuredError(res, {
+                    statusCode: 403,
+                    error: 'flag_disabled',
+                    reason: 'flag_disabled',
+                    nextAction: 'Enable the intent_engineering feature flag first.',
+                });
+                return;
+            }
+            const model = getModel(workspaceDir);
+            const result = await model.getRawContent(flagEnabled, lang);
+            if (!result.ok) {
+                // Map model error reason → HTTP status (rc-9-no-silent-fallback).
+                // not_found → 404; oversized → 413 (Payload Too Large, matches the
+                // byte-budget contract with getSummary); read_error / unknown → 500.
+                const statusCode = result.reason === 'not_found' ? 404 :
+                    result.reason === 'oversized' ? 413 :
+                        result.reason === 'flag_disabled' ? 403 :
+                            500;
+                sendStructuredError(res, {
+                    statusCode,
+                    error: result.reason ?? 'intent_content_error',
+                    reason: result.reason ?? 'unknown',
+                    nextAction: result.nextAction,
+                });
+                return;
+            }
+            sendSuccess(res, { content: result.content, path: result.path });
+            return;
+        }
+        // ── GET /api/v1/intent/versions — list version history ────────────────
+        if (req.method === 'GET' && subPath === '/versions') {
+            const model = getModel(workspaceDir);
+            const result = await model.getVersions(lang);
+            if (!result.ok) {
+                sendSuccess(res, { versions: [], reason: result.reason, nextAction: result.nextAction });
+                return;
+            }
+            sendSuccess(res, { versions: result.versions });
+            return;
+        }
+        // ── POST /api/v1/intent/init — create INTENT.md template ──────────────
+        if (req.method === 'POST' && subPath === '/init') {
+            const flagEnabled = loadFlagEnabled(workspaceDir);
+            if (!flagEnabled) {
+                sendStructuredError(res, {
+                    statusCode: 403,
+                    error: 'flag_disabled',
+                    reason: 'flag_disabled',
+                    nextAction: 'Enable the intent_engineering feature flag first.',
+                });
+                return;
+            }
+            const body = await readBody(req);
+            let parsedBody = {};
+            if (body.trim().length > 0) {
+                try {
+                    parsedBody = JSON.parse(body);
+                }
+                catch {
+                    sendStructuredError(res, {
+                        statusCode: 400,
+                        error: 'bad_request',
+                        reason: 'invalid_json',
+                        nextAction: 'Request body must be valid JSON.',
+                    });
+                    return;
+                }
+            }
+            // Extract force flag (default false — don't overwrite existing file)
+            let force = false;
+            if (parsedBody !== null && typeof parsedBody === 'object' && Object.hasOwn(parsedBody, 'force')) {
+                const forceVal = parsedBody.force;
+                if (typeof forceVal === 'boolean') {
+                    force = forceVal;
+                }
+            }
+            const model = getModel(workspaceDir);
+            const result = await model.createTemplate(flagEnabled, force, lang);
+            if (result.ok) {
+                if (result.created) {
+                    sendJson(res, 201, { success: true, data: result });
+                }
+                else {
+                    // already_exists — return 200 with reason
+                    sendSuccess(res, result);
+                }
+            }
+            else {
+                sendStructuredError(res, {
+                    statusCode: 500,
+                    error: 'intent_init_error',
+                    reason: result.reason ?? 'unknown',
+                    nextAction: result.nextAction,
+                });
+            }
+            return;
+        }
+        // ── PUT /api/v1/intent/content — save INTENT.md content ───────────────
+        if (req.method === 'PUT' && subPath === '/content') {
+            const flagEnabled = loadFlagEnabled(workspaceDir);
+            if (!flagEnabled) {
+                sendStructuredError(res, {
+                    statusCode: 403,
+                    error: 'flag_disabled',
+                    reason: 'flag_disabled',
+                    nextAction: 'Enable the intent_engineering feature flag first.',
+                });
+                return;
+            }
+            const body = await readBody(req);
+            let parsedBody;
+            try {
+                parsedBody = JSON.parse(body);
+            }
+            catch {
+                sendStructuredError(res, {
+                    statusCode: 400,
+                    error: 'bad_request',
+                    reason: 'invalid_json',
+                    nextAction: 'Request body must be valid JSON.',
+                });
+                return;
+            }
+            // Runtime Contract Rule #1: treat as unknown, validate with Object.hasOwn
+            if (parsedBody === null || typeof parsedBody !== 'object' || Array.isArray(parsedBody)) {
+                sendStructuredError(res, {
+                    statusCode: 400,
+                    error: 'bad_request',
+                    reason: 'invalid_body',
+                    nextAction: 'Request body must be a JSON object with a "content" field.',
+                });
+                return;
+            }
+            const bodyObj = parsedBody;
+            if (!Object.hasOwn(bodyObj, 'content')) {
+                sendStructuredError(res, {
+                    statusCode: 400,
+                    error: 'bad_request',
+                    reason: 'missing_content',
+                    nextAction: 'Request body must include a "content" string field.',
+                });
+                return;
+            }
+            const model = getModel(workspaceDir);
+            const result = await model.saveContent(flagEnabled, bodyObj.content, lang);
+            if (result.ok) {
+                sendSuccess(res, result);
+            }
+            else {
+                // Map known reasons to HTTP status codes
+                const statusCode = result.reason === 'invalid_content' || result.reason === 'empty_content' || result.reason === 'oversized'
+                    ? 400
+                    : 500;
+                sendStructuredError(res, {
+                    statusCode,
+                    error: 'intent_save_error',
+                    reason: result.reason ?? 'unknown',
+                    nextAction: result.nextAction,
+                });
+            }
+            return;
+        }
+        // ── Unknown sub-path ──────────────────────────────────────────────────
+        sendError(res, 404, 'not_found', `Route /api/v1/intent${subPath} not found`);
     }
     catch (err) {
         sendError(res, 500, 'intent_route_error', err instanceof Error ? err.message : 'Unknown error');

package/console/dist/types.d.ts

@@ -82,5 +82,6 @@ export type ApiResponse<T> = {
 } | {
     success: false;
     error: string;
+    reason?: string;
     nextAction?: string;
 };