@agent-facets/core 0.1.1 → 0.1.3

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @agent-facets/core
 
+## 0.1.3
+
+### Patch Changes
+
+- [`098fd08`](https://github.com/agent-facets/facets/commit/098fd08bf5d9970babc5c57bee6a155bffcecd97) Thanks [@eXamadeus](https://github.com/eXamadeus)! - Better CLI parameter validation
+
+- [`5262cbe`](https://github.com/agent-facets/facets/commit/5262cbe66df02c625430309878e6061ccde183de) Thanks [@eXamadeus](https://github.com/eXamadeus)! - Fix publishing by properly categorizing dev dependencies
+
+- [`d3b9439`](https://github.com/agent-facets/facets/commit/d3b9439466e0eb65687901426e2ebd6c5a333c60) Thanks [@eXamadeus](https://github.com/eXamadeus)! - Use better github attribution for changesets
+
+## 0.1.2
+
+### Patch Changes
+
+- bb87748: This is a CI improvement so we release faster and cleaner
+- 95e2f38: Migrate NPM packages from `@ex-machina` to `@agent-facets` org.
+
+  - `@ex-machina/facet-core` is now `@agent-facets/core`
+  - `@ex-machina/facet` is now `agent-facets`
+
 ## 0.1.1
 
 ### Patch Changes

package/package.json

@@ -5,25 +5,28 @@
     "url": "https://github.com/agent-facets/facets",
     "directory": "packages/core"
   },
-  "version": "0.1.1",
+  "version": "0.1.3",
   "type": "module",
   "exports": {
     ".": "./src/index.ts"
   },
   "scripts": {
+    "prepack": "bun ../../scripts/prepack.ts",
+    "postpack": "bun ../../scripts/postpack.ts",
     "types": "tsc --noEmit",
     "test": "bun test"
   },
   "dependencies": {
     "arktype": "2.1.29",
     "comment-json": "^4.2.5",
-    "nanotar": "0.3.0"
+    "nanotar": "0.3.0",
+    "yaml": "2.8.3"
   },
   "devDependencies": {
     "@types/bun": "1.3.10"
   },
   "peerDependencies": {
-    "typescript": "^5"
+    "typescript": "^5 || ^6"
   },
   "publishConfig": {
     "access": "public",

package/src/__tests__/build-pipeline.test.ts

@@ -206,7 +206,7 @@ describe('validatePlatformConfigs', () => {
 describe('runBuildPipeline', () => {
   test('successful build with valid facet', async () => {
     const dir = await createFixtureDir('valid-build')
-    await Bun.write(join(dir, 'skills/example.md'), '# Example skill')
+    await Bun.write(join(dir, 'skills/example/SKILL.md'), '# Example skill')
     await Bun.write(
       join(dir, 'facet.json'),
       JSON.stringify({
@@ -230,8 +230,8 @@ describe('runBuildPipeline', () => {
       expect(result.archiveFilename).toBe('test-facet-1.0.0.facet')
       expect(result.archiveBytes.length).toBeGreaterThan(0)
       expect(Object.keys(result.assetHashes)).toContain('facet.json')
-      expect(Object.keys(result.assetHashes)).toContain('skills/example.md')
-      expect(result.assetHashes['skills/example.md']).toMatchInlineSnapshot(
+      expect(Object.keys(result.assetHashes)).toContain('skills/example/SKILL.md')
+      expect(result.assetHashes['skills/example/SKILL.md']).toMatchInlineSnapshot(
         `"sha256:ded8057927e03783371d0d929e4a6e92da66eb9dd164377ad6845a5a1c0cb5ba"`,
       )
       expect(result.integrity).toMatch(/^sha256:[a-f0-9]{64}$/)
@@ -263,13 +263,13 @@ describe('runBuildPipeline', () => {
     expect(result.ok).toBe(false)
     if (!result.ok) {
       expect(result.errors[0]?.path).toBe('skills.example')
-      expect(result.errors[0]?.message).toContain('skills/example.md')
+      expect(result.errors[0]?.message).toContain('skills/example/SKILL.md')
     }
   })
 
   test('build succeeds with cross-type name sharing', async () => {
     const dir = await createFixtureDir('cross-type')
-    await Bun.write(join(dir, 'skills/review.md'), '# Review skill')
+    await Bun.write(join(dir, 'skills/review/SKILL.md'), '# Review skill')
     await Bun.write(join(dir, 'commands/review.md'), '# Review command')
     await Bun.write(
       join(dir, 'facet.json'),
@@ -291,8 +291,8 @@ describe('runBuildPipeline', () => {
 
   test('build with all asset types includes all hashes', async () => {
     const dir = await createFixtureDir('all-types')
-    await Bun.write(join(dir, 'skills/alpha.md'), '# Alpha skill')
-    await Bun.write(join(dir, 'skills/beta.md'), '# Beta skill')
+    await Bun.write(join(dir, 'skills/alpha/SKILL.md'), '# Alpha skill')
+    await Bun.write(join(dir, 'skills/beta/SKILL.md'), '# Beta skill')
     await Bun.write(join(dir, 'agents/helper.md'), '# Helper agent')
     await Bun.write(join(dir, 'commands/deploy.md'), '# Deploy command')
     await Bun.write(
@@ -322,15 +322,15 @@ describe('runBuildPipeline', () => {
         'agents/helper.md',
         'commands/deploy.md',
         'facet.json',
-        'skills/alpha.md',
-        'skills/beta.md',
+        'skills/alpha/SKILL.md',
+        'skills/beta/SKILL.md',
       ])
     }
   })
 
   test('build fails on malformed compact facets entry', async () => {
     const dir = await createFixtureDir('bad-facets')
-    await Bun.write(join(dir, 'skills/x.md'), '# Skill')
+    await Bun.write(join(dir, 'skills/x/SKILL.md'), '# Skill')
     await Bun.write(
       join(dir, 'facet.json'),
       JSON.stringify({
@@ -351,12 +351,89 @@ describe('runBuildPipeline', () => {
   })
 })
 
+// --- Content validation ---
+
+describe('content validation', () => {
+  test('build fails on file with YAML front matter', async () => {
+    const dir = await createFixtureDir('front-matter')
+    await Bun.write(
+      join(dir, 'skills/review/SKILL.md'),
+      '---\nname: Review\ndescription: A review skill\n---\n# Review\nReview all code.',
+    )
+    await Bun.write(
+      join(dir, 'facet.json'),
+      JSON.stringify({
+        name: 'test-facet',
+        version: '1.0.0',
+        skills: {
+          review: { description: 'A review skill' },
+        },
+      }),
+    )
+
+    const result = await runBuildPipeline(dir)
+    expect(result.ok).toBe(false)
+    if (!result.ok) {
+      expect(result.errors).toHaveLength(1)
+      expect(result.errors[0]?.path).toBe('skills.review')
+      expect(result.errors[0]?.message).toContain('front matter')
+      expect(result.errors[0]?.message).toContain('skills/review/SKILL.md')
+    }
+  })
+
+  test('build fails on empty content file', async () => {
+    const dir = await createFixtureDir('empty-file')
+    await Bun.write(join(dir, 'skills/empty/SKILL.md'), '')
+    await Bun.write(
+      join(dir, 'facet.json'),
+      JSON.stringify({
+        name: 'test-facet',
+        version: '1.0.0',
+        skills: {
+          empty: { description: 'An empty skill' },
+        },
+      }),
+    )
+
+    const result = await runBuildPipeline(dir)
+    expect(result.ok).toBe(false)
+    if (!result.ok) {
+      expect(result.errors).toHaveLength(1)
+      expect(result.errors[0]?.path).toBe('skills.empty')
+      expect(result.errors[0]?.message).toContain('empty')
+    }
+  })
+
+  test('build fails on whitespace-only content file', async () => {
+    const dir = await createFixtureDir('whitespace-file')
+    await Bun.write(join(dir, 'agents/blank.md'), '   \n\n  \n')
+    await Bun.write(
+      join(dir, 'facet.json'),
+      JSON.stringify({
+        name: 'test-facet',
+        version: '1.0.0',
+        agents: {
+          blank: { description: 'A blank agent' },
+        },
+      }),
+    )
+
+    const result = await runBuildPipeline(dir)
+    expect(result.ok).toBe(false)
+    if (!result.ok) {
+      expect(result.errors).toHaveLength(1)
+      expect(result.errors[0]?.path).toBe('agents.blank')
+      expect(result.errors[0]?.message).toContain('empty')
+    }
+  })
+})
+
 // --- Build output generation ---
 
 describe('writeBuildOutput', () => {
   test('writes archive and build manifest to dist/', async () => {
     const dir = await createFixtureDir('write-output')
-    await Bun.write(join(dir, 'skills/example.md'), '# Resolved content')
+    await Bun.write(join(dir, 'skills/example/SKILL.md'), '# Resolved content')
     await Bun.write(
       join(dir, 'facet.json'),
       JSON.stringify({
@@ -385,7 +462,7 @@ describe('writeBuildOutput', () => {
     expect(manifest.archive).toBe('test-facet-1.0.0.facet')
     expect(manifest.integrity).toMatch(/^sha256:[a-f0-9]{64}$/)
     expect(manifest.assets['facet.json']).toMatch(/^sha256:[a-f0-9]{64}$/)
-    expect(manifest.assets['skills/example.md']).toMatch(/^sha256:[a-f0-9]{64}$/)
+    expect(manifest.assets['skills/example/SKILL.md']).toMatch(/^sha256:[a-f0-9]{64}$/)
 
     // No loose files
     const looseManifest = await Bun.file(join(dir, 'dist/facet.json')).exists()
@@ -394,7 +471,7 @@ describe('writeBuildOutput', () => {
 
   test('cleans previous dist/ before writing', async () => {
     const dir = await createFixtureDir('clean-dist')
-    await Bun.write(join(dir, 'skills/x.md'), '# Skill')
+    await Bun.write(join(dir, 'skills/x/SKILL.md'), '# Skill')
     await Bun.write(
       join(dir, 'facet.json'),
       JSON.stringify({

package/src/__tests__/content-hash.test.ts

@@ -63,7 +63,7 @@ describe('collectArchiveEntries', () => {
 
     expect(entries).toHaveLength(4)
     expect(entries.map((e) => e.path)).toContain('facet.json')
-    expect(entries.map((e) => e.path)).toContain('skills/review.md')
+    expect(entries.map((e) => e.path)).toContain('skills/review/SKILL.md')
     expect(entries.map((e) => e.path)).toContain('agents/helper.md')
     expect(entries.map((e) => e.path)).toContain('commands/deploy.md')
   })
@@ -84,7 +84,7 @@ describe('collectArchiveEntries', () => {
     const entries = collectArchiveEntries(resolved, 'manifest content')
     const paths = entries.map((e) => e.path)
 
-    expect(paths).toEqual(['agents/b-agent.md', 'facet.json', 'skills/a-skill.md', 'skills/z-skill.md'])
+    expect(paths).toEqual(['agents/b-agent.md', 'facet.json', 'skills/a-skill/SKILL.md', 'skills/z-skill/SKILL.md'])
   })
 
   test('handles manifest with no optional asset types', () => {
@@ -105,7 +105,7 @@ describe('computeAssetHashes', () => {
   test('returns correct hash for each entry', () => {
     const entries = [
       { path: 'facet.json', content: '{"name":"test"}' },
-      { path: 'skills/review.md', content: '# Review' },
+      { path: 'skills/review/SKILL.md', content: '# Review' },
     ]
 
     const hashes = computeAssetHashes(entries)
@@ -114,7 +114,7 @@ describe('computeAssetHashes', () => {
     expect(hashes['facet.json']).toMatchInlineSnapshot(
       `"sha256:7d9fd2051fc32b32feab10946fab6bb91426ab7e39aa5439289ed892864aa91d"`,
     )
-    expect(hashes['skills/review.md']).toMatchInlineSnapshot(
+    expect(hashes['skills/review/SKILL.md']).toMatchInlineSnapshot(
       `"sha256:f1a9d9d60fba2e67d82d788760d147d95461a58456411e205bf33a6dbdc3497f"`,
     )
   })
@@ -134,7 +134,7 @@ describe('assembleTar', () => {
   test('produces a valid tar archive', () => {
     const entries = [
       { path: 'facet.json', content: '{"name":"test","version":"1.0.0"}' },
-      { path: 'skills/review.md', content: '# Review skill' },
+      { path: 'skills/review/SKILL.md', content: '# Review skill' },
     ]
 
     const tar = assembleTar(entries)
@@ -147,7 +147,7 @@ describe('assembleTar', () => {
 
     const names = parsed.map((f) => f.name)
     expect(names).toContain('facet.json')
-    expect(names).toContain('skills/review.md')
+    expect(names).toContain('skills/review/SKILL.md')
   })
 
   test('tar contains correct file contents', () => {
@@ -205,7 +205,7 @@ describe('compressArchive', () => {
   test('compressed archive can be decompressed to recover original tar', async () => {
     const entries = [
       { path: 'facet.json', content: '{"name":"test","version":"1.0.0"}' },
-      { path: 'skills/review.md', content: '# Review skill' },
+      { path: 'skills/review/SKILL.md', content: '# Review skill' },
     ]
 
     const tar = assembleTar(entries)
@@ -220,7 +220,7 @@ describe('compressArchive', () => {
 
     const names = parsed.map((f) => f.name)
     expect(names).toContain('facet.json')
-    expect(names).toContain('skills/review.md')
-    expect(parsed.find((f) => f.name === 'skills/review.md')?.text).toBe('# Review skill')
+    expect(names).toContain('skills/review/SKILL.md')
+    expect(parsed.find((f) => f.name === 'skills/review/SKILL.md')?.text).toBe('# Review skill')
   })
 })

package/src/__tests__/edit.test.ts

@@ -0,0 +1,190 @@
+import { describe, expect, test } from 'bun:test'
+import { mkdir } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { writeManifest } from '../edit/manifest-writer.ts'
+import { reconcile } from '../edit/reconcile.ts'
+import type { DiscoveredAsset } from '../edit/scanner.ts'
+import { scanAssets } from '../edit/scanner.ts'
+import type { FacetManifest } from '../schemas/facet-manifest.ts'
+
+async function createFixtureDir(name: string): Promise<string> {
+  const dir = join(tmpdir(), `facets-edit-test-${name}-${Date.now()}`)
+  await mkdir(dir, { recursive: true })
+  return dir
+}
+
+// --- Scanner ---
+
+describe('scanAssets', () => {
+  test('discovers skills in directory convention', async () => {
+    const dir = await createFixtureDir('scan-skills')
+    await mkdir(join(dir, 'skills/review'), { recursive: true })
+    await mkdir(join(dir, 'skills/code-fix'), { recursive: true })
+    await Bun.write(join(dir, 'skills/review/SKILL.md'), '# Review')
+    await Bun.write(join(dir, 'skills/code-fix/SKILL.md'), '# Code Fix')
+
+    const assets = await scanAssets(dir)
+    expect(assets.filter((a) => a.type === 'skills')).toHaveLength(2)
+    expect(assets.find((a) => a.name === 'review')).toBeDefined()
+    expect(assets.find((a) => a.name === 'code-fix')).toBeDefined()
+  })
+
+  test('discovers agents and commands in flat convention', async () => {
+    const dir = await createFixtureDir('scan-flat')
+    await mkdir(join(dir, 'agents'), { recursive: true })
+    await mkdir(join(dir, 'commands'), { recursive: true })
+    await Bun.write(join(dir, 'agents/reviewer.md'), '# Reviewer')
+    await Bun.write(join(dir, 'commands/deploy.md'), '# Deploy')
+
+    const assets = await scanAssets(dir)
+    expect(assets.find((a) => a.type === 'agents' && a.name === 'reviewer')).toBeDefined()
+    expect(assets.find((a) => a.type === 'commands' && a.name === 'deploy')).toBeDefined()
+  })
+
+  test('skips non-kebab-case names', async () => {
+    const dir = await createFixtureDir('scan-skip')
+    await mkdir(join(dir, 'skills/InvalidName'), { recursive: true })
+    await mkdir(join(dir, 'agents'), { recursive: true })
+    await Bun.write(join(dir, 'skills/InvalidName/SKILL.md'), '# Bad')
+    await Bun.write(join(dir, 'agents/NOT_VALID.md'), '# Bad')
+
+    const assets = await scanAssets(dir)
+    expect(assets).toHaveLength(0)
+  })
+
+  test('returns empty for directory with no assets', async () => {
+    const dir = await createFixtureDir('scan-empty')
+    const assets = await scanAssets(dir)
+    expect(assets).toHaveLength(0)
+  })
+
+  test('returns sorted results', async () => {
+    const dir = await createFixtureDir('scan-sorted')
+    await mkdir(join(dir, 'skills/zebra'), { recursive: true })
+    await mkdir(join(dir, 'agents'), { recursive: true })
+    await mkdir(join(dir, 'skills/alpha'), { recursive: true })
+    await Bun.write(join(dir, 'skills/zebra/SKILL.md'), '# Z')
+    await Bun.write(join(dir, 'skills/alpha/SKILL.md'), '# A')
+    await Bun.write(join(dir, 'agents/beta.md'), '# B')
+
+    const assets = await scanAssets(dir)
+    const names = assets.map((a) => `${a.type}:${a.name}`)
+    expect(names).toEqual(['agents:beta', 'skills:alpha', 'skills:zebra'])
+  })
+})
+
+// --- Reconciliation ---
+
+describe('reconcile', () => {
+  test('identifies additions (on disk, not in manifest)', () => {
+    const manifest: FacetManifest = {
+      name: 'test',
+      version: '1.0.0',
+      skills: { review: { description: 'Review skill' } },
+    }
+    const discovered: DiscoveredAsset[] = [
+      { type: 'skills', name: 'review', path: 'skills/review/SKILL.md' },
+      { type: 'skills', name: 'new-skill', path: 'skills/new-skill/SKILL.md' },
+      { type: 'agents', name: 'helper', path: 'agents/helper.md' },
+    ]
+
+    const result = reconcile(manifest, discovered)
+    expect(result.additions).toHaveLength(2)
+    expect(result.additions.find((a) => a.name === 'new-skill')).toBeDefined()
+    expect(result.additions.find((a) => a.name === 'helper')).toBeDefined()
+  })
+
+  test('identifies missing files (in manifest, not on disk)', () => {
+    const manifest: FacetManifest = {
+      name: 'test',
+      version: '1.0.0',
+      skills: {
+        review: { description: 'Review' },
+        gone: { description: 'Gone' },
+      },
+    }
+    const discovered: DiscoveredAsset[] = [{ type: 'skills', name: 'review', path: 'skills/review/SKILL.md' }]
+
+    const result = reconcile(manifest, discovered)
+    expect(result.missing).toHaveLength(1)
+    expect(result.missing[0]?.name).toBe('gone')
+    expect(result.missing[0]?.expectedPath).toBe('skills/gone/SKILL.md')
+  })
+
+  test('identifies matched assets', () => {
+    const manifest: FacetManifest = {
+      name: 'test',
+      version: '1.0.0',
+      agents: { reviewer: { description: 'Review agent' } },
+    }
+    const discovered: DiscoveredAsset[] = [{ type: 'agents', name: 'reviewer', path: 'agents/reviewer.md' }]
+
+    const result = reconcile(manifest, discovered)
+    expect(result.matched).toHaveLength(1)
+    expect(result.matched[0]?.name).toBe('reviewer')
+    expect(result.additions).toHaveLength(0)
+    expect(result.missing).toHaveLength(0)
+  })
+
+  test('handles manifest with no assets', () => {
+    const manifest: FacetManifest = {
+      name: 'test',
+      version: '1.0.0',
+      facets: ['base@1.0.0'],
+    }
+    const discovered: DiscoveredAsset[] = [{ type: 'skills', name: 'extra', path: 'skills/extra/SKILL.md' }]
+
+    const result = reconcile(manifest, discovered)
+    expect(result.additions).toHaveLength(1)
+    expect(result.missing).toHaveLength(0)
+    expect(result.matched).toHaveLength(0)
+  })
+
+  test('missing agent has flat file expected path', () => {
+    const manifest: FacetManifest = {
+      name: 'test',
+      version: '1.0.0',
+      agents: { gone: { description: 'Gone' } },
+    }
+
+    const result = reconcile(manifest, [])
+    expect(result.missing[0]?.expectedPath).toBe('agents/gone.md')
+  })
+})
+
+// --- Manifest Writer ---
+
+describe('writeManifest', () => {
+  test('writes valid JSON to facet.json', async () => {
+    const dir = await createFixtureDir('write-manifest')
+    const manifest: FacetManifest = {
+      name: 'test-facet',
+      version: '1.0.0',
+      skills: { review: { description: 'A review skill' } },
+    }
+
+    await writeManifest(manifest, dir)
+
+    const content = await Bun.file(join(dir, 'facet.json')).text()
+    const parsed = JSON.parse(content)
+    expect(parsed.name).toBe('test-facet')
+    expect(parsed.version).toBe('1.0.0')
+    expect(parsed.skills.review.description).toBe('A review skill')
+  })
+
+  test('output is 2-space indented', async () => {
+    const dir = await createFixtureDir('write-indent')
+    const manifest: FacetManifest = {
+      name: 'test',
+      version: '1.0.0',
+      skills: { x: { description: 'X' } },
+    }
+
+    await writeManifest(manifest, dir)
+
+    const content = await Bun.file(join(dir, 'facet.json')).text()
+    // 2-space indent means lines like '  "name": "test"'
+    expect(content).toContain('  "name"')
+  })
+})

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

@@ -174,7 +174,7 @@ describe('loadManifest', () => {
 describe('resolvePrompts', () => {
   test('prompt content is resolved from conventional file paths', async () => {
     const dir = await createFixtureDir('resolve-convention')
-    await writeFixture(dir, 'skills/review.md', '# Code Review\nReview all code.')
+    await writeFixture(dir, 'skills/review/SKILL.md', '# Code Review\nReview all code.')
     await writeFixture(dir, 'agents/reviewer.md', '# Reviewer\nReview this code.')
     await writeFixture(dir, 'commands/deploy.md', '# Deploy\nDeploy the code.')
 
@@ -242,7 +242,7 @@ describe('resolvePrompts', () => {
 
   test('manifest without agents or commands resolves successfully', async () => {
     const dir = await createFixtureDir('resolve-skills-only')
-    await writeFixture(dir, 'skills/x.md', '# Skill X\nDo x.')
+    await writeFixture(dir, 'skills/x/SKILL.md', '# Skill X\nDo x.')
 
     const manifest = {
       name: 'test',

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'),
   }))
 }
 

package/src/schemas/facet-manifest.ts

@@ -2,7 +2,7 @@ import { type } from 'arktype'
 
 // --- Sub-schemas ---
 
-/** Skill descriptor — description is required, prompt resolved from skills/<name>.md */
+/** Skill descriptor — description is required, prompt resolved from skills/<name>/SKILL.md */
 const SkillDescriptor = type({
   description: 'string',
   'platforms?': type.Record('string', 'unknown'),
@@ -37,9 +37,11 @@ const ServerReference = type('string').or({ image: 'string' })
 // --- Main schema ---
 
 /**
- * The structural schema for the facet manifest — validates shape only.
- * Custom constraints (at least one text asset, selective entry must select at least one type)
- * are checked post-validation by checkFacetManifestConstraints().
+ * The facet manifest schema — validates structure and business constraints.
+ *
+ * Structural validation covers field types and shapes. Narrow constraints enforce:
+ * 1. At least one text asset (skills, agents, commands, or facets) must be present
+ * 2. Selective facets entries must include at least one asset type selection
  */
 export const FacetManifestSchema = type({
   name: 'string',
@@ -51,63 +53,35 @@ export const FacetManifestSchema = type({
   'commands?': type.Record('string', CommandDescriptor),
   'facets?': FacetsEntry.array(),
   'servers?': type.Record('string', ServerReference),
-})
-
-/** Inferred TypeScript type for a validated facet manifest */
-export type FacetManifest = typeof FacetManifestSchema.infer
-
-// --- Custom validation ---
-
-export interface FacetManifestError {
-  path: string
-  message: string
-  expected: string
-  actual: string
-}
-
-/**
- * Checks business-rule constraints that ArkType's structural validation cannot express:
- * 1. At least one text asset must be present (skills, agents, commands, or facets)
- * 2. Selective facets entries must include at least one asset type
- */
-export function checkFacetManifestConstraints(manifest: FacetManifest): FacetManifestError[] {
-  const errors: FacetManifestError[] = []
-
+}).narrow((data, ctx) => {
   // Constraint 1: at least one text asset
-  const hasSkills = manifest.skills && Object.keys(manifest.skills).length > 0
-  const hasAgents = manifest.agents && Object.keys(manifest.agents).length > 0
-  const hasCommands = manifest.commands && Object.keys(manifest.commands).length > 0
-  const hasFacets = manifest.facets && manifest.facets.length > 0
+  const hasSkills = data.skills && Object.keys(data.skills).length > 0
+  const hasAgents = data.agents && Object.keys(data.agents).length > 0
+  const hasCommands = data.commands && Object.keys(data.commands).length > 0
+  const hasFacets = data.facets && data.facets.length > 0
 
   if (!hasSkills && !hasAgents && !hasCommands && !hasFacets) {
-    errors.push({
-      path: '',
-      message: 'Manifest must include at least one text asset (skills, agents, commands, or facets)',
-      expected: 'at least one of: skills, agents, commands, facets',
-      actual: 'none present',
-    })
+    ctx.mustBe('Manifest must include at least one text asset (skills, agents, commands, or facets)')
   }
 
   // Constraint 2: selective facets entries must select at least one asset type
-  if (manifest.facets) {
-    for (let i = 0; i < manifest.facets.length; i++) {
-      const entry = manifest.facets[i]
+  if (data.facets) {
+    for (let i = 0; i < data.facets.length; i++) {
+      const entry = data.facets[i]
       if (typeof entry === 'object') {
         const hasSelectedSkills = entry.skills && entry.skills.length > 0
         const hasSelectedAgents = entry.agents && entry.agents.length > 0
         const hasSelectedCommands = entry.commands && entry.commands.length > 0
 
         if (!hasSelectedSkills && !hasSelectedAgents && !hasSelectedCommands) {
-          errors.push({
-            path: `facets[${i}]`,
-            message: 'Selective facets entry must include at least one asset type (skills, agents, or commands)',
-            expected: 'at least one of: skills, agents, commands',
-            actual: 'none selected',
-          })
+          ctx.mustBe('Selective facets entry must include at least one asset type (skills, agents, or commands)')
         }
       }
     }
   }
 
-  return errors
-}
+  return true
+})
+
+/** Inferred TypeScript type for a validated facet manifest */
+export type FacetManifest = typeof FacetManifestSchema.infer