@agent-facets/core 0.1.2 → 0.2.0

package/src/__tests__/facet-manifest.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, test } from 'bun:test'
 import { type } from 'arktype'
-import { checkFacetManifestConstraints, type FacetManifest, FacetManifestSchema } from '../schemas/facet-manifest.ts'
+import { type FacetManifest, FacetManifestSchema } from '../schemas/facet-manifest.ts'
 
 // --- Valid manifests ---
 
@@ -88,9 +88,6 @@ describe('FacetManifestSchema — valid manifests', () => {
     }
     const result = FacetManifestSchema(input)
     expect(result).not.toBeInstanceOf(type.errors)
-    const data = result as FacetManifest
-    const errors = checkFacetManifestConstraints(data)
-    expect(errors).toHaveLength(0)
   })
 })
 
@@ -137,38 +134,29 @@ describe('FacetManifestSchema — invalid manifests', () => {
     const errors = result as InstanceType<typeof type.errors>
     expect(errors.some((e) => e.path.includes('bad'))).toBe(true)
   })
-})
-
-// --- Business-rule constraints ---
 
-describe('checkFacetManifestConstraints', () => {
-  test('no text assets → error', () => {
+  test('no text assets → schema error', () => {
     const input = {
       name: 'empty',
       version: '1.0.0',
       servers: { jira: '1.0.0' },
     }
     const result = FacetManifestSchema(input)
-    expect(result).not.toBeInstanceOf(type.errors)
-    const errors = checkFacetManifestConstraints(result as FacetManifest)
-    expect(errors).toHaveLength(1)
-    const firstError = errors[0]
-    expect(firstError).toBeDefined()
-    expect(firstError?.message).toContain('at least one text asset')
+    expect(result).toBeInstanceOf(type.errors)
+    const errors = result as InstanceType<typeof type.errors>
+    expect(errors.some((e) => e.message.includes('at least one text asset'))).toBe(true)
   })
 
-  test('selective facets entry with no asset selection → error', () => {
+  test('selective facets entry with no asset selection → schema error', () => {
     const input = {
       name: 'bad-selective',
       version: '1.0.0',
       facets: [{ name: 'other', version: '1.0.0' }],
     }
     const result = FacetManifestSchema(input)
-    expect(result).not.toBeInstanceOf(type.errors)
-    const errors = checkFacetManifestConstraints(result as FacetManifest)
-    const selectiveError = errors.find((e) => e.message.includes('at least one asset type'))
-    expect(selectiveError).toBeDefined()
-    expect(selectiveError?.path).toBe('facets[0]')
+    expect(result).toBeInstanceOf(type.errors)
+    const errors = result as InstanceType<typeof type.errors>
+    expect(errors.some((e) => e.message.includes('at least one asset type'))).toBe(true)
   })
 })
 

package/src/build/content-hash.ts

@@ -27,7 +27,7 @@ export function collectArchiveEntries(resolved: ResolvedFacetManifest, manifestC
 
   if (resolved.skills) {
     for (const [name, skill] of Object.entries(resolved.skills)) {
-      entries.push({ path: `skills/${name}.md`, content: skill.prompt })
+      entries.push({ path: `skills/${name}/SKILL.md`, content: skill.prompt })
     }
   }
 

package/src/build/pipeline.ts

@@ -9,11 +9,12 @@ import {
   computeContentHash,
 } from './content-hash.ts'
 import { detectNamingCollisions } from './detect-collisions.ts'
+import { validateContentFiles } from './validate-content.ts'
 import { validateCompactFacets } from './validate-facets.ts'
 import { validatePlatformConfigs } from './validate-platforms.ts'
 
 export interface BuildProgress {
-  stage: string
+  stage: BuildStage
   status: 'running' | 'done' | 'failed'
 }
 
@@ -33,19 +34,33 @@ export interface BuildFailure {
   warnings: string[]
 }
 
+/** Stage names emitted by the build pipeline via the onProgress callback. */
+export const BUILD_STAGES = [
+  'Parsing manifest',
+  'Resolving prompts',
+  'Validating assets',
+  'Checking collisions',
+  'Validating platforms',
+  'Assembling archive',
+  'Writing output',
+] as const
+
+export type BuildStage = (typeof BUILD_STAGES)[number]
+
 /**
  * Runs the full build pipeline:
- * 1. Load manifest — read the facet manifest, parse JSON, validate schema, check constraints
- * 2. Resolve prompts — read prompt files at conventional paths for skills, agents, commands (also verifies files exist)
- * 3. Validate compact facets format — check name@version pattern
- * 4. Detect naming collisions — fail if same name used within an asset type
- * 5. Validate platform config — check known platform schemas, warn on unknown
- * 6. Assemble archive — collect entries, compute per-asset hashes, build deterministic tar, compute integrity hash, compress for delivery
+ * 1. Parse manifest — read facet.json, parse JSON, validate schema, check constraints
+ * 2. Resolve prompts — read prompt files at conventional paths (also verifies files exist)
+ * 3. Validate content — no front matter, no empty files
+ * 4. Check collisions — fail if same name used within an asset type
+ * 5. Validate platforms — check known platform schemas, warn on unknown
+ * 6. Assemble archive — collect entries, compute hashes, build tar, compress
  *
  * Returns the resolved manifest and archive data on success, or collected errors on failure.
  * Warnings are returned in both cases.
  *
  * An optional `onProgress` callback receives stage updates for UI display.
+ * The 'Writing output' stage is emitted by name but handled by the caller (BuildView).
  */
 export async function runBuildPipeline(
   rootDir: string,
@@ -53,46 +68,64 @@ export async function runBuildPipeline(
 ): Promise<BuildResult | BuildFailure> {
   const warnings: string[] = []
 
-  // Stage 1: Load manifest
-  onProgress?.({ stage: 'Validating manifest', status: 'running' })
+  // Stage 1: Parse manifest
+  onProgress?.({ stage: 'Parsing manifest', status: 'running' })
 
   const loadResult = await loadManifest(rootDir)
   if (!loadResult.ok) {
-    onProgress?.({ stage: 'Validating manifest', status: 'failed' })
+    onProgress?.({ stage: 'Parsing manifest', status: 'failed' })
     return { ok: false, errors: loadResult.errors, warnings }
   }
   const manifest = loadResult.data
 
+  onProgress?.({ stage: 'Parsing manifest', status: 'done' })
+
   // Stage 2: Resolve prompts (also serves as file existence verification)
+  onProgress?.({ stage: 'Resolving prompts', status: 'running' })
+
   const resolveResult = await resolvePrompts(manifest, rootDir)
   if (!resolveResult.ok) {
-    onProgress?.({ stage: 'Validating manifest', status: 'failed' })
+    onProgress?.({ stage: 'Resolving prompts', status: 'failed' })
     return { ok: false, errors: resolveResult.errors, warnings }
   }
 
-  // Stage 3: Validate compact facets format
-  const facetsErrors = validateCompactFacets(manifest)
-  if (facetsErrors.length > 0) {
-    onProgress?.({ stage: 'Validating manifest', status: 'failed' })
-    return { ok: false, errors: facetsErrors, warnings }
+  onProgress?.({ stage: 'Resolving prompts', status: 'done' })
+
+  // Stage 3: Validate assets (no front matter, no empty files)
+  onProgress?.({ stage: 'Validating assets', status: 'running' })
+
+  const contentErrors = validateContentFiles(resolveResult.data)
+  if (contentErrors.length > 0) {
+    onProgress?.({ stage: 'Validating assets', status: 'failed' })
+    return { ok: false, errors: contentErrors, warnings }
   }
 
-  // Stage 4: Detect naming collisions
+  onProgress?.({ stage: 'Validating assets', status: 'done' })
+
+  // Stage 4: Check naming collisions
+  onProgress?.({ stage: 'Checking collisions', status: 'running' })
+
   const collisionErrors = detectNamingCollisions(manifest)
-  if (collisionErrors.length > 0) {
-    onProgress?.({ stage: 'Validating manifest', status: 'failed' })
-    return { ok: false, errors: collisionErrors, warnings }
+  const facetsErrors = validateCompactFacets(manifest)
+  const checkErrors = [...collisionErrors, ...facetsErrors]
+  if (checkErrors.length > 0) {
+    onProgress?.({ stage: 'Checking collisions', status: 'failed' })
+    return { ok: false, errors: checkErrors, warnings }
   }
 
+  onProgress?.({ stage: 'Checking collisions', status: 'done' })
+
   // Stage 5: Validate platform config
+  onProgress?.({ stage: 'Validating platforms', status: 'running' })
+
   const platformResult = validatePlatformConfigs(manifest)
   if (platformResult.errors.length > 0) {
-    onProgress?.({ stage: 'Validating manifest', status: 'failed' })
+    onProgress?.({ stage: 'Validating platforms', status: 'failed' })
     return { ok: false, errors: platformResult.errors, warnings: [...warnings, ...platformResult.warnings] }
   }
   warnings.push(...platformResult.warnings)
 
-  onProgress?.({ stage: 'Validating manifest', status: 'done' })
+  onProgress?.({ stage: 'Validating platforms', status: 'done' })
 
   // Stage 6: Assemble archive, compute content hashes, and compress for delivery
   onProgress?.({ stage: 'Assembling archive', status: 'running' })

package/src/build/validate-content.ts

@@ -0,0 +1,50 @@
+import { hasFrontMatter } from '../front-matter.ts'
+import type { ResolvedFacetManifest } from '../loaders/facet.ts'
+import type { ValidationError } from '../types.ts'
+
+/**
+ * Validates resolved prompt content for all assets:
+ * - No YAML front matter (manifest is the single source of truth for metadata)
+ * - No empty files (zero bytes or whitespace only)
+ *
+ * Returns an array of validation errors, one per offending file.
+ */
+export function validateContentFiles(resolved: ResolvedFacetManifest): ValidationError[] {
+  const errors: ValidationError[] = []
+
+  const assetTypes = [
+    { type: 'skills', assets: resolved.skills },
+    { type: 'agents', assets: resolved.agents },
+    { type: 'commands', assets: resolved.commands },
+  ] as const
+
+  for (const { type, assets } of assetTypes) {
+    if (!assets) continue
+    for (const [name, asset] of Object.entries(assets)) {
+      const relativePath = type === 'skills' ? `skills/${name}/SKILL.md` : `${type}/${name}.md`
+
+      // Check for empty content
+      if (asset.prompt.trim().length === 0) {
+        errors.push({
+          path: `${type}.${name}`,
+          message: `File is empty: ${relativePath}. Content files must contain prompt content.`,
+          expected: 'non-empty content',
+          actual: 'empty or whitespace only',
+        })
+        continue // Skip front matter check on empty files
+      }
+
+      // Check for YAML front matter
+      if (hasFrontMatter(asset.prompt)) {
+        errors.push({
+          path: `${type}.${name}`,
+          message: `File contains YAML front matter: ${relativePath}. The manifest is the source of truth for metadata — use \`facet edit\` to reconcile.`,
+          expected: 'no front matter',
+          actual: 'front matter detected',
+        })
+      }
+    }
+  }
+
+  return errors
+}

package/src/edit/manifest-writer.ts

@@ -0,0 +1,12 @@
+import { join } from 'node:path'
+import { FACET_MANIFEST_FILE } from '../loaders/facet.ts'
+import type { FacetManifest } from '../schemas/facet-manifest.ts'
+
+/**
+ * Writes a facet manifest to disk as `facet.json`.
+ * Uses `JSON.stringify(data, null, 2)` per ADR-006.
+ */
+export async function writeManifest(manifest: FacetManifest, rootDir: string): Promise<void> {
+  const path = join(rootDir, FACET_MANIFEST_FILE)
+  await Bun.write(path, JSON.stringify(manifest, null, 2))
+}

package/src/edit/reconcile.ts

@@ -0,0 +1,77 @@
+import type { FacetManifest } from '../schemas/facet-manifest.ts'
+import type { AssetType, DiscoveredAsset } from './scanner.ts'
+
+export interface MissingAsset {
+  type: AssetType
+  name: string
+  /** The path where the file was expected (e.g., 'skills/review/SKILL.md') */
+  expectedPath: string
+}
+
+export interface MatchedAsset {
+  type: AssetType
+  name: string
+  /** Relative path from the facet root */
+  path: string
+}
+
+export interface ReconciliationResult {
+  /** Assets found on disk but not in the manifest */
+  additions: DiscoveredAsset[]
+  /** Assets in the manifest but missing from disk */
+  missing: MissingAsset[]
+  /** Assets that exist in both the manifest and on disk */
+  matched: MatchedAsset[]
+}
+
+/**
+ * Compares discovered assets on disk against manifest entries.
+ * Produces lists of additions (on disk, not in manifest),
+ * missing files (in manifest, not on disk), and matched assets.
+ */
+export function reconcile(manifest: FacetManifest, discovered: DiscoveredAsset[]): ReconciliationResult {
+  const additions: DiscoveredAsset[] = []
+  const missing: MissingAsset[] = []
+  const matched: MatchedAsset[] = []
+
+  // Build a set of discovered assets keyed by type:name
+  const discoveredMap = new Map<string, DiscoveredAsset>()
+  for (const asset of discovered) {
+    discoveredMap.set(`${asset.type}:${asset.name}`, asset)
+  }
+
+  // Check manifest entries against discovered assets
+  const assetSections: Array<{ type: AssetType; entries: Record<string, unknown> | undefined }> = [
+    { type: 'skills', entries: manifest.skills },
+    { type: 'agents', entries: manifest.agents },
+    { type: 'commands', entries: manifest.commands },
+  ]
+
+  const manifestKeys = new Set<string>()
+
+  for (const { type, entries } of assetSections) {
+    if (!entries) continue
+    for (const name of Object.keys(entries)) {
+      const key = `${type}:${name}`
+      manifestKeys.add(key)
+
+      const onDisk = discoveredMap.get(key)
+      if (onDisk) {
+        matched.push({ type, name, path: onDisk.path })
+      } else {
+        const expectedPath = type === 'skills' ? `skills/${name}/SKILL.md` : `${type}/${name}.md`
+        missing.push({ type, name, expectedPath })
+      }
+    }
+  }
+
+  // Check discovered assets not in manifest
+  for (const asset of discovered) {
+    const key = `${asset.type}:${asset.name}`
+    if (!manifestKeys.has(key)) {
+      additions.push(asset)
+    }
+  }
+
+  return { additions, missing, matched }
+}

package/src/edit/scanner.ts

@@ -0,0 +1,57 @@
+import { Glob } from 'bun'
+
+/** Kebab-case pattern for valid asset names. */
+export const KEBAB_CASE = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/
+
+export type AssetType = 'skills' | 'agents' | 'commands'
+
+export interface DiscoveredAsset {
+  type: AssetType
+  name: string
+  /** Relative path from the facet root (e.g., 'skills/review/SKILL.md') */
+  path: string
+}
+
+/**
+ * Scans a facet directory for content files and returns discovered assets.
+ *
+ * Skills use the directory convention: `skills/<name>/SKILL.md`
+ * Agents use the flat convention: `agents/<name>.md`
+ * Commands use the flat convention: `commands/<name>.md`
+ *
+ * Only assets with valid kebab-case names are returned.
+ */
+export async function scanAssets(rootDir: string): Promise<DiscoveredAsset[]> {
+  const assets: DiscoveredAsset[] = []
+
+  // Scan skills: skills/*/SKILL.md
+  const skillGlob = new Glob('skills/*/SKILL.md')
+  for await (const match of skillGlob.scan({ cwd: rootDir, onlyFiles: true })) {
+    // match is e.g. 'skills/review/SKILL.md'
+    const parts = match.split('/')
+    const name = parts[1]
+    if (name && KEBAB_CASE.test(name)) {
+      assets.push({ type: 'skills', name, path: match })
+    }
+  }
+
+  // Scan agents: agents/*.md
+  const agentGlob = new Glob('agents/*.md')
+  for await (const match of agentGlob.scan({ cwd: rootDir, onlyFiles: true })) {
+    const name = match.replace('agents/', '').replace('.md', '')
+    if (KEBAB_CASE.test(name)) {
+      assets.push({ type: 'agents', name, path: match })
+    }
+  }
+
+  // Scan commands: commands/*.md
+  const commandGlob = new Glob('commands/*.md')
+  for await (const match of commandGlob.scan({ cwd: rootDir, onlyFiles: true })) {
+    const name = match.replace('commands/', '').replace('.md', '')
+    if (KEBAB_CASE.test(name)) {
+      assets.push({ type: 'commands', name, path: match })
+    }
+  }
+
+  return assets.sort((a, b) => a.type.localeCompare(b.type) || a.name.localeCompare(b.name))
+}

package/src/front-matter.ts

@@ -0,0 +1,58 @@
+import { parse as parseYaml } from 'yaml'
+
+/**
+ * Matches YAML front matter: opening `---`, YAML content, closing `---`.
+ * Anchored to start of string. Handles optional trailing content.
+ */
+const FRONT_MATTER_RE = /^---\n([\s\S]*?)\n---(?:\n([\s\S]*))?$/
+
+/** Matches empty front matter: `---\n---` with optional trailing content. */
+const EMPTY_FRONT_MATTER_RE = /^---\n---(?:\n([\s\S]*))?$/
+
+/** Normalize BOM and line endings to LF. */
+function normalize(raw: string): string {
+  return raw
+    .replace(/^\uFEFF/, '')
+    .replace(/\r\n/g, '\n')
+    .replace(/\r/g, '\n')
+}
+
+/** Returns true if the string contains YAML front matter. */
+export function hasFrontMatter(raw: string): boolean {
+  const input = normalize(raw)
+  return FRONT_MATTER_RE.test(input) || EMPTY_FRONT_MATTER_RE.test(input)
+}
+
+export interface FrontMatterResult<T = Record<string, unknown>> {
+  /** Parsed YAML attributes. Empty object if no front matter or parse failure. */
+  data: T
+  /** Markdown body with front matter stripped. Original content if no front matter. */
+  content: string
+}
+
+/**
+ * Extracts YAML front matter attributes and clean body from a string.
+ * Returns the original content unchanged if no front matter is found.
+ * Treats YAML parse failures as "no front matter" (returns empty data + original content).
+ */
+export function extractFrontMatter<T = Record<string, unknown>>(raw: string): FrontMatterResult<T> {
+  const input = normalize(raw)
+
+  const emptyMatch = input.match(EMPTY_FRONT_MATTER_RE)
+  if (emptyMatch) {
+    return { data: {} as T, content: emptyMatch[1] ?? '' }
+  }
+
+  const match = input.match(FRONT_MATTER_RE)
+  if (!match) {
+    return { data: {} as T, content: raw }
+  }
+
+  try {
+    const yaml = match[1] ?? ''
+    return { data: (parseYaml(yaml) ?? {}) as T, content: match[2] ?? '' }
+  } catch {
+    // Malformed YAML — treat as no front matter
+    return { data: {} as T, content: raw }
+  }
+}

package/src/index.ts

@@ -1,5 +1,4 @@
 // types
-
 export type { ArchiveEntry } from './build/content-hash.ts'
 export {
   assembleTar,
@@ -9,13 +8,22 @@ export {
   computeContentHash,
 } from './build/content-hash.ts'
 export { detectNamingCollisions } from './build/detect-collisions.ts'
-export type { BuildFailure, BuildProgress, BuildResult } from './build/pipeline.ts'
+export type { BuildFailure, BuildProgress, BuildResult, BuildStage } from './build/pipeline.ts'
 // build pipeline
-export { runBuildPipeline } from './build/pipeline.ts'
+export { BUILD_STAGES, runBuildPipeline } from './build/pipeline.ts'
 export { validateCompactFacets } from './build/validate-facets.ts'
 export type { PlatformValidationResult } from './build/validate-platforms.ts'
 export { validatePlatformConfigs } from './build/validate-platforms.ts'
 export { writeBuildOutput } from './build/write-output.ts'
+export { writeManifest } from './edit/manifest-writer.ts'
+export type { MatchedAsset, MissingAsset, ReconciliationResult } from './edit/reconcile.ts'
+export { reconcile } from './edit/reconcile.ts'
+// edit
+export type { AssetType, DiscoveredAsset } from './edit/scanner.ts'
+export { KEBAB_CASE, scanAssets } from './edit/scanner.ts'
+// front matter
+export type { FrontMatterResult } from './front-matter.ts'
+export { extractFrontMatter, hasFrontMatter } from './front-matter.ts'
 export type { ResolvedFacetManifest } from './loaders/facet.ts'
 // loaders
 export { FACET_MANIFEST_FILE, loadManifest, resolvePrompts } from './loaders/facet.ts'
@@ -24,10 +32,7 @@ export type { BuildManifest } from './schemas/build-manifest.ts'
 export { BuildManifestSchema } from './schemas/build-manifest.ts'
 export type { FacetManifest } from './schemas/facet-manifest.ts'
 // schemas
-export {
-  checkFacetManifestConstraints,
-  FacetManifestSchema,
-} from './schemas/facet-manifest.ts'
+export { FacetManifestSchema } from './schemas/facet-manifest.ts'
 export type { Lockfile } from './schemas/lockfile.ts'
 export { LockfileSchema } from './schemas/lockfile.ts'
 export type { ServerManifest } from './schemas/server-manifest.ts'

package/src/loaders/facet.ts

@@ -1,6 +1,6 @@
 import { join } from 'node:path'
 import { type } from 'arktype'
-import { checkFacetManifestConstraints, type FacetManifest, FacetManifestSchema } from '../schemas/facet-manifest.ts'
+import { type FacetManifest, FacetManifestSchema } from '../schemas/facet-manifest.ts'
 import type { Result, ValidationError } from '../types.ts'
 import { mapArkErrors, parseJson, readFile } from './validate.ts'
 
@@ -34,18 +34,13 @@ export async function loadManifest(dir: string): Promise<Result<FacetManifest>>
     return { ok: false, errors: mapArkErrors(validated) }
   }
 
-  // Phase 3: Business-rule constraints
-  const constraintErrors = checkFacetManifestConstraints(validated)
-  if (constraintErrors.length > 0) {
-    return { ok: false, errors: constraintErrors }
-  }
-
   return { ok: true, data: validated }
 }
 
 /**
  * A manifest with all prompts resolved to their string content.
- * File paths are derived from convention: `<type>/<name>.md`.
+ * File paths are derived from convention: skills use `skills/<name>/SKILL.md`,
+ * agents use `agents/<name>.md`, commands use `commands/<name>.md`.
  */
 export interface ResolvedFacetManifest {
   name: string
@@ -83,8 +78,9 @@ export interface ResolvedFacetManifest {
  * Resolves prompt content for all skills, agents, and commands by reading
  * files at conventional paths relative to the facet root directory.
  *
- * The convention is `<type>/<name>.md` — for example, a skill named
- * "code-review" resolves to `skills/code-review.md`.
+ * Skills use the Agent Skills directory convention: a skill named "code-review"
+ * resolves to `skills/code-review/SKILL.md`. Agents and commands use the flat
+ * file convention: `agents/<name>.md` and `commands/<name>.md`.
  *
  * This also serves as file existence verification for all three asset types —
  * if an expected file doesn't exist, resolution fails with an error identifying
@@ -96,7 +92,7 @@ export interface ResolvedFacetManifest {
 export async function resolvePrompts(manifest: FacetManifest, rootDir: string): Promise<Result<ResolvedFacetManifest>> {
   const errors: ValidationError[] = []
 
-  // Resolve skill prompts from skills/<name>.md
+  // Resolve skill prompts from skills/<name>/SKILL.md
   let resolvedSkills: ResolvedFacetManifest['skills'] | undefined
   if (manifest.skills) {
     resolvedSkills = {}
@@ -158,11 +154,13 @@ export async function resolvePrompts(manifest: FacetManifest, rootDir: string):
 }
 
 /**
- * Resolves prompt content for a single asset by reading <type>/<name>.md.
+ * Resolves prompt content for a single asset by reading the file at its
+ * conventional path. Skills use `skills/<name>/SKILL.md` (Agent Skills
+ * directory convention). Agents and commands use `<type>/<name>.md`.
  * Returns the file content as a string, or a ValidationError if the file doesn't exist.
  */
 async function resolveAssetPrompt(assetType: string, name: string, rootDir: string): Promise<string | ValidationError> {
-  const relativePath = `${assetType}/${name}.md`
+  const relativePath = assetType === 'skills' ? `${assetType}/${name}/SKILL.md` : `${assetType}/${name}.md`
   const filePath = join(rootDir, relativePath)
   const file = Bun.file(filePath)
   const exists = await file.exists()

package/src/loaders/validate.ts

@@ -8,9 +8,11 @@ import type { ValidationError } from '../types.ts'
 export function mapArkErrors(errors: InstanceType<typeof type.errors>): ValidationError[] {
   return errors.map((err) => ({
     path: err.path.join('.'),
-    message: err.message,
+    // For predicate errors (.narrow()), err.message includes the full data object.
+    // Use err.expected directly — it's our clean sentence from ctx.mustBe().
+    message: err.code === 'predicate' ? (err.expected ?? err.message) : err.message,
     expected: err.expected ?? 'unknown',
-    actual: err.actual ?? 'unknown',
+    actual: err.code === 'predicate' ? 'constraint not met' : (err.actual ?? 'unknown'),
   }))
 }