diff --git a/openspec/changes/support-non-asset-files/tasks.md b/openspec/changes/support-non-asset-files/tasks.md
index 020149a1..b432734d 100644
--- a/openspec/changes/support-non-asset-files/tasks.md
+++ b/openspec/changes/support-non-asset-files/tasks.md
@@ -125,10 +125,10 @@
 
 - [x] 13.1 Implement: Add an editable default `README.md` scaffold option and template that writes the file and top-level declaration atomically without regenerating authored content after identity edits
 - [x] 13.2 Implement: Add the dedicated create README card/editor flow, optional disable behavior, state snapshotting, and explicit confirmation preview, and align headless create with the documented policy
-- [ ] 13.3 Implement: Extend edit scanning and reconciliation for undeclared skill companions, common root files, and missing declared supplementary files while routing only exact `README.md` and `README` paths to a dedicated panel
+- [x] 13.3 Implement: Extend edit scanning and reconciliation for undeclared skill companions, common root files, and missing declared supplementary files while routing only exact `README.md` and `README` paths to a dedicated panel
 - [ ] 13.4 Implement: Add independent tagged states and actions for both conventional README paths, preserving bytes on adoption and retaining exact paths for scaffold, edit, removal, and declaration changes
-- [ ] 13.5 Implement: Replace string-parsed reconciliation keys with stable structured identities and represent file/declaration operations as tagged variants with no invalid combinations
-- [ ] 13.6 Implement: Apply README, companion, and generic supplementary changes transactionally with manifest edits and show every queued exact-path operation before Apply
+- [x] 13.5 Implement: Replace string-parsed reconciliation keys with stable structured identities and represent file/declaration operations as tagged variants with no invalid combinations
+- [x] 13.6 Implement: Apply README, companion, and generic supplementary changes transactionally with manifest edits and show every queued exact-path operation before Apply
 - [ ] 13.7 Implement: Add engine, CLI, TUI, integration, and create-build end-to-end tests covering README defaults/disable/edit preservation in interactive and headless creates, both README paths, adoption, missing-file choices, companion discovery, skill deletion preserving undeclared files, confirmation, cancellation, and buildability
 - [ ] 13.8 Verify: Run focused scaffold, edit, create, TUI, integration, and end-to-end tests
 
diff --git a/packages/cli/src/__tests__/edit-integration.test.ts b/packages/cli/src/__tests__/edit-integration.test.ts
index a94fc7a3..5d286540 100644
--- a/packages/cli/src/__tests__/edit-integration.test.ts
+++ b/packages/cli/src/__tests__/edit-integration.test.ts
@@ -33,9 +33,9 @@ describe('edit integration', () => {
     const result = await buildEditContext(dir)
     expect(result.ok).toBe(true)
     if (!result.ok) expect.unreachable()
-    const additions = result.context.reconciliationItems.filter((i) => i.kind === 'addition')
+    const additions = result.context.reconciliationItems.filter((i) => i.kind === 'asset-addition')
     expect(additions).toHaveLength(1)
-    expect(additions[0]?.name).toBe('new-one')
+    expect(additions[0]?.kind === 'asset-addition' && additions[0].name).toBe('new-one')
   })
 
   test('buildEditContext detects missing files in manifest', async () => {
@@ -55,9 +55,9 @@ describe('edit integration', () => {
     const result = await buildEditContext(dir)
     expect(result.ok).toBe(true)
     if (!result.ok) expect.unreachable()
-    const missing = result.context.reconciliationItems.filter((i) => i.kind === 'missing')
+    const missing = result.context.reconciliationItems.filter((i) => i.kind === 'asset-missing')
     expect(missing).toHaveLength(1)
-    expect(missing[0]?.name).toBe('gone')
+    expect(missing[0]?.kind === 'asset-missing' && missing[0].name).toBe('gone')
   })
 
   test('buildEditContext does NOT flag matched files that contain front matter', async () => {
@@ -97,9 +97,13 @@ describe('edit integration', () => {
       version: '1.0.0',
       skills: { helper: { description: 'A helper skill' } },
     }
-    const operations: EditOperation[] = [{ op: 'write-manifest' }, { op: 'scaffold', type: 'skills', name: 'helper' }]
+    const operations: EditOperation[] = [
+      { op: 'write-manifest', manifest },
+      { op: 'scaffold-asset', assetType: 'skills', name: 'helper' },
+    ]
 
-    await applyOperations(manifest, operations, dir)
+    const applied = await applyOperations(operations, dir)
+    expect(applied.ok).toBe(true)
 
     const manifestExists = await Bun.file(join(dir, 'facet.json')).exists()
     expect(manifestExists).toBe(true)
@@ -114,9 +118,13 @@ describe('edit integration', () => {
     await Bun.write(join(dir, 'skills/old/SKILL.md'), '# Old skill')
 
     const manifest = { name: 'test', version: '1.0.0', skills: { remaining: { description: 'Remaining' } } }
-    const operations: EditOperation[] = [{ op: 'write-manifest' }, { op: 'delete-file', type: 'skills', name: 'old' }]
+    const operations: EditOperation[] = [
+      { op: 'write-manifest', manifest },
+      { op: 'delete-asset', assetType: 'skills', name: 'old', companionPaths: [] },
+    ]
 
-    await applyOperations(manifest, operations, dir)
+    const applied = await applyOperations(operations, dir)
+    expect(applied.ok).toBe(true)
 
     const deleted = await Bun.file(join(dir, 'skills/old/SKILL.md')).exists()
     expect(deleted).toBe(false)
@@ -129,9 +137,13 @@ describe('edit integration', () => {
       version: '1.0.0',
       skills: { example: { description: 'An example skill' } },
     }
-    const operations: EditOperation[] = [{ op: 'write-manifest' }, { op: 'scaffold', type: 'skills', name: 'example' }]
+    const operations: EditOperation[] = [
+      { op: 'write-manifest', manifest },
+      { op: 'scaffold-asset', assetType: 'skills', name: 'example' },
+    ]
 
-    await applyOperations(manifest, operations, dir)
+    const applied = await applyOperations(operations, dir)
+    expect(applied.ok).toBe(true)
 
     const buildResult = await runBuildPipeline(dir)
     expect(buildResult.ok).toBe(true)
diff --git a/packages/cli/src/commands/edit/index.ts b/packages/cli/src/commands/edit/index.ts
index 36b7bf64..84eb75d6 100644
--- a/packages/cli/src/commands/edit/index.ts
+++ b/packages/cli/src/commands/edit/index.ts
@@ -24,11 +24,24 @@ export const editCommand: Command = {
     if (!loaded.ok) return loaded.exitCode
 
     const buildArg = args[0] ? ` ${displayDir}` : ''
+    let applyError: string | null = null
     const completed = await runEditWizardInk(loaded.context, {
-      onApply: (result) => applyEditOperations(result.manifest, result.operations, rootDir),
+      onApply: async (result) => {
+        const applied = await applyEditOperations(result.operations, rootDir)
+        if (!applied.ok) {
+          applyError = `Failed to apply changes at ${applied.failedPath}: ${applied.reason}${
+            applied.rollbackOk ? ' (rolled back)' : ' (rollback incomplete)'
+          }`
+        }
+      },
       buildArg,
     })
 
+    if (applyError) {
+      console.error(applyError)
+      return 1
+    }
+
     if (!completed) {
       console.log('\nCancelled — no changes applied.')
       return 1
diff --git a/packages/cli/src/tui/views/__tests__/confirm-privacy.test.tsx b/packages/cli/src/tui/views/__tests__/confirm-privacy.test.tsx
index 744416f8..deda3cab 100644
--- a/packages/cli/src/tui/views/__tests__/confirm-privacy.test.tsx
+++ b/packages/cli/src/tui/views/__tests__/confirm-privacy.test.tsx
@@ -49,7 +49,7 @@ function renderEdit(isPrivate: boolean) {
   return render(
     <FocusOrderProvider>
       <FormStateProvider initialState={formWith(isPrivate)}>
-        <EditConfirmView onConfirm={() => {}} onBack={() => {}} />
+        <EditConfirmView operations={[]} onConfirm={() => {}} onBack={() => {}} />
       </FormStateProvider>
     </FocusOrderProvider>,
   )
diff --git a/packages/cli/src/tui/views/edit/edit-confirm-view.tsx b/packages/cli/src/tui/views/edit/edit-confirm-view.tsx
index 5d32c399..1e77ba8c 100644
--- a/packages/cli/src/tui/views/edit/edit-confirm-view.tsx
+++ b/packages/cli/src/tui/views/edit/edit-confirm-view.tsx
@@ -1,4 +1,5 @@
 import { ASSET_TYPE_COLORS } from '@agent-facets/brand'
+import { type EditOperation, previewEditOperations } from '@agent-facets/engine'
 import { Box, Text } from 'ink'
 import { useEffect } from 'react'
 import { truncateDescription } from '../../components/asset-description.tsx'
@@ -15,9 +16,18 @@ const ASSET_LABELS: Record<AssetSectionKey, string> = {
   agent: 'Agents',
 }
 
-export function EditConfirmView({ onConfirm, onBack }: { onConfirm: () => void; onBack: () => void }) {
+export function EditConfirmView({
+  operations,
+  onConfirm,
+  onBack,
+}: {
+  operations: EditOperation[]
+  onConfirm: () => void
+  onBack: () => void
+}) {
   const { form } = useFormState()
   const { setFocusIds, focus, focusedId } = useFocusOrder()
+  const opLines = previewEditOperations(operations)
 
   useEffect(() => {
     setFocusIds(['edit-apply-btn', 'edit-back-btn'])
@@ -78,6 +88,25 @@ export function EditConfirmView({ onConfirm, onBack }: { onConfirm: () => void;
         )
       })}
 
+      <Box flexDirection="column" marginTop={1}>
+        <Text bold color={THEME.success}>
+          File changes:
+        </Text>
+        {opLines.length === 0 ? (
+          <Box marginLeft={2}>
+            <Text dimColor>(manifest only)</Text>
+          </Box>
+        ) : (
+          opLines.map((line) => (
+            <Box key={`${line.verb}:${line.path}`} marginLeft={2}>
+              <Text color={THEME.hint}>
+                {line.verb} {line.path}
+              </Text>
+            </Box>
+          ))
+        )}
+      </Box>
+
       <Box marginTop={1} gap={2}>
         <Button
           id="edit-apply-btn"
diff --git a/packages/cli/src/tui/views/edit/reconciliation-view.tsx b/packages/cli/src/tui/views/edit/reconciliation-view.tsx
index 6cbb9c5d..860217fe 100644
--- a/packages/cli/src/tui/views/edit/reconciliation-view.tsx
+++ b/packages/cli/src/tui/views/edit/reconciliation-view.tsx
@@ -1,47 +1,35 @@
-import type { ReconciliationItem, ReconciliationResolution } from '@agent-facets/engine'
+import {
+  isAdditionItem,
+  optionIndexForResolution,
+  optionLabelsFor,
+  type ReconciliationItem,
+  type ReconciliationResolution,
+  reconciliationItemKey,
+  resolutionForOption,
+} from '@agent-facets/engine'
 import { Box, Text } from 'ink'
 import { useCallback, useEffect, useMemo } from 'react'
 import { Button } from '../../components/button.tsx'
 import { ReconciliationItemRow } from '../../components/reconciliation-item.tsx'
 import { useFocusOrder } from '../../context/focus-order-context.ts'
 import { THEME } from '../../theme.ts'
-
-/** Maps a reconciliation item to a unique key. */
-function itemKey(item: ReconciliationItem): string {
-  return `${item.kind}:${item.type}:${item.name}`
-}
-
-/** Returns the two action options for a reconciliation item kind. */
-function optionsForKind(kind: ReconciliationItem['kind']): [{ label: string }, { label: string }] {
-  switch (kind) {
-    case 'addition':
-      return [{ label: 'Add to manifest' }, { label: 'Ignore for now' }]
-    case 'missing':
-      return [{ label: 'Scaffold template' }, { label: 'Remove from manifest' }]
-  }
-}
-
-/** Converts a selected option index to a resolution for the given item kind. */
-function indexToResolution(kind: ReconciliationItem['kind'], index: number): ReconciliationResolution {
-  switch (kind) {
-    case 'addition':
-      return index === 0 ? { action: 'add-to-manifest' } : { action: 'ignore' }
-    case 'missing':
-      return index === 0 ? { action: 'scaffold-template' } : { action: 'remove-from-manifest' }
-  }
-}
-
-/** Returns the selected option index for a resolution, or null. */
-function resolutionToIndex(
-  kind: ReconciliationItem['kind'],
-  resolution: ReconciliationResolution | undefined,
-): number | null {
-  if (!resolution) return null
-  switch (kind) {
-    case 'addition':
-      return resolution.action === 'add-to-manifest' ? 0 : resolution.action === 'ignore' ? 1 : null
-    case 'missing':
-      return resolution.action === 'scaffold-template' ? 0 : resolution.action === 'remove-from-manifest' ? 1 : null
+import type { ResolvedItem } from './use-edit-session.ts'
+
+/** Human-readable primary line for a reconciliation item, from structured fields. */
+function itemDescription(item: ReconciliationItem): string {
+  switch (item.kind) {
+    case 'asset-addition':
+      return item.path
+    case 'asset-missing':
+      return `${item.name} (${item.assetType}) — ${item.expectedPath}`
+    case 'companion-addition':
+      return item.path
+    case 'companion-missing':
+      return item.expectedPath
+    case 'root-addition':
+      return item.path
+    case 'root-missing':
+      return item.path
   }
 }
 
@@ -52,21 +40,19 @@ export function ReconciliationView({
   onContinue,
 }: {
   items: ReconciliationItem[]
-  resolutions: Map<string, ReconciliationResolution>
-  onResolve: (key: string, resolution: ReconciliationResolution) => void
+  resolutions: Map<string, ResolvedItem>
+  onResolve: (item: ReconciliationItem, resolution: ReconciliationResolution) => void
   onContinue: () => void
 }) {
   const { setFocusIds, focusedId, focus } = useFocusOrder()
 
-  const allResolved = items.every((item) => resolutions.has(itemKey(item)))
+  const allResolved = items.every((item) => resolutions.has(reconciliationItemKey(item)))
 
-  // Group items by kind
-  const additions = items.filter((i) => i.kind === 'addition')
-  const missing = items.filter((i) => i.kind === 'missing')
+  const additions = items.filter((i) => isAdditionItem(i))
+  const missing = items.filter((i) => !isAdditionItem(i))
 
-  // Build focus order: all items then continue button
   const focusIds = useMemo(() => {
-    const ids = items.map((item) => `recon-${itemKey(item)}`)
+    const ids = items.map((item) => `recon-${reconciliationItemKey(item)}`)
     ids.push('recon-continue')
     return ids
   }, [items])
@@ -80,22 +66,20 @@ export function ReconciliationView({
 
   const handleSelect = useCallback(
     (item: ReconciliationItem, optionIndex: number) => {
-      const key = itemKey(item)
-      const resolution = indexToResolution(item.kind, optionIndex)
-      onResolve(key, resolution)
+      const key = reconciliationItemKey(item)
+      onResolve(item, resolutionForOption(item, optionIndex))
 
-      // Auto-advance to next unresolved item
-      const currentIdx = items.findIndex((i) => itemKey(i) === key)
+      // Auto-advance to the next unresolved item.
+      const currentIdx = items.findIndex((i) => reconciliationItemKey(i) === key)
       for (let i = currentIdx + 1; i < items.length; i++) {
         const nextItem = items[i]
         if (!nextItem) continue
-        const nextKey = itemKey(nextItem)
+        const nextKey = reconciliationItemKey(nextItem)
         if (!resolutions.has(nextKey)) {
           focus(`recon-${nextKey}`)
           return
         }
       }
-      // All resolved — focus continue button
       focus('recon-continue')
     },
     [items, resolutions, onResolve, focus],
@@ -111,16 +95,15 @@ export function ReconciliationView({
           </Text>
         </Box>
         {groupItems.map((item) => {
-          const key = itemKey(item)
-          const description = item.kind === 'missing' ? `${item.name} (${item.type}) — ${item.expectedPath}` : item.path
-
+          const key = reconciliationItemKey(item)
+          const [a, b] = optionLabelsFor(item)
           return (
             <ReconciliationItemRow
               key={key}
               id={`recon-${key}`}
-              description={description}
-              options={optionsForKind(item.kind)}
-              selectedIndex={resolutionToIndex(item.kind, resolutions.get(key))}
+              description={itemDescription(item)}
+              options={[{ label: a }, { label: b }]}
+              selectedIndex={optionIndexForResolution(item, resolutions.get(key)?.resolution)}
               onSelect={(index) => handleSelect(item, index)}
             />
           )
diff --git a/packages/cli/src/tui/views/edit/success-view.tsx b/packages/cli/src/tui/views/edit/success-view.tsx
index f133a105..8e5dc248 100644
--- a/packages/cli/src/tui/views/edit/success-view.tsx
+++ b/packages/cli/src/tui/views/edit/success-view.tsx
@@ -1,14 +1,9 @@
-import type { EditOperation } from '@agent-facets/engine'
+import { type EditOperation, previewEditOperations } from '@agent-facets/engine'
 import { Box, Text } from 'ink'
 import { THEME } from '../../theme.ts'
 
 export function EditSuccessView({ operations, buildArg }: { operations: EditOperation[]; buildArg: string }) {
-  const scaffolded = operations.filter((op) => op.op === 'scaffold').length
-  const deleted = operations.filter((op) => op.op === 'delete-file').length
-  const parts: string[] = []
-  if (scaffolded > 0) parts.push(`${scaffolded} scaffolded`)
-  if (deleted > 0) parts.push(`${deleted} removed`)
-  parts.push('manifest updated')
+  const lines = previewEditOperations(operations)
 
   return (
     <Box flexDirection="column">
@@ -17,8 +12,12 @@ export function EditSuccessView({ operations, buildArg }: { operations: EditOper
           Changes applied.
         </Text>
       </Text>
-      <Box marginLeft={2}>
-        <Text color={THEME.hint}>{parts.join(' · ')}</Text>
+      <Box flexDirection="column" marginLeft={2}>
+        {lines.map((line) => (
+          <Text key={`${line.verb}:${line.path}`} color={THEME.hint}>
+            {line.verb} {line.path}
+          </Text>
+        ))}
       </Box>
       <Text color={THEME.hint}>Run "facet build{buildArg}" to validate your facet.</Text>
     </Box>
diff --git a/packages/cli/src/tui/views/edit/use-edit-session.ts b/packages/cli/src/tui/views/edit/use-edit-session.ts
index 4ea27ea1..43dba265 100644
--- a/packages/cli/src/tui/views/edit/use-edit-session.ts
+++ b/packages/cli/src/tui/views/edit/use-edit-session.ts
@@ -1,8 +1,25 @@
-import type { EditContext, EditOperation, EditResult, ReconciliationResolution } from '@agent-facets/engine'
+import {
+  addSkillCompanion,
+  addTopLevelFile,
+  type EditContext,
+  type EditOperation,
+  type EditResult,
+  type ReconciliationItem,
+  type ReconciliationResolution,
+  reconciliationItemKey,
+  removeSkillCompanion,
+  removeTopLevelFile,
+} from '@agent-facets/engine'
 import type { FacetManifest } from '@agent-facets/protocol'
 import { useCallback, useState } from 'react'
 import type { AssetSectionKey, FormState } from '../../context/form-state-context.ts'
 
+/** A resolved reconciliation item: the structured item plus the chosen action. */
+export interface ResolvedItem {
+  item: ReconciliationItem
+  resolution: ReconciliationResolution
+}
+
 /** Maps form section keys to manifest asset keys. */
 const FORM_TO_MANIFEST: Record<AssetSectionKey, 'skills' | 'agents' | 'commands'> = {
   skill: 'skills',
@@ -23,11 +40,7 @@ export function buildManifest(original: FacetManifest, form: FormState): FacetMa
   }
 
   // Privacy is handled after `...original` so a private→public edit actively
-  // removes a spread-in `private: true`. The form is binary, but the manifest
-  // can represent public either by omission or by an explicit `private: false`:
-  // - private              → write `private: true`
-  // - public + original false → preserve `private: false` (already spread in)
-  // - public + original omitted/true → delete `private`
+  // removes a spread-in `private: true`.
   if (form.private) {
     manifest.private = true
   } else if (original.private !== false) {
@@ -41,10 +54,8 @@ export function buildManifest(original: FacetManifest, form: FormState): FacetMa
     const items = form.assets[formKey].items
     if (items.length > 0) {
       // Start each descriptor from the original so descriptor-level metadata
-      // (notably per-asset `adapters` front-matter, which the form never
-      // surfaces) survives the edit round-trip. Only `description` — the one
-      // field the form edits — is overwritten. New assets have no original
-      // descriptor, so they collapse to `{ description }`.
+      // (per-asset `adapters`, and skill `files` companion declarations) survives
+      // the round-trip. Only `description` is overwritten from the form.
       const originalSection = original[manifestKey]
       const section: NonNullable<FacetManifest[typeof manifestKey]> = {}
       for (const name of items) {
@@ -63,72 +74,109 @@ export function buildManifest(original: FacetManifest, form: FormState): FacetMa
   return manifest
 }
 
-/** Builds the list of file operations from resolutions + form changes. */
+/**
+ * Apply supplementary-declaration deltas (companion/root add/remove) to the
+ * form-derived manifest. Supplementary files are not modeled in the form, so
+ * their declaration changes are applied here as pure manifest mutations. README
+ * declarations are handled by the README panel, not here.
+ */
+function applySupplementaryDeltas(manifest: FacetManifest, resolved: ResolvedItem[]): FacetManifest {
+  let next = manifest
+  for (const { item, resolution } of resolved) {
+    switch (item.kind) {
+      case 'companion-addition':
+        if (resolution.action === 'add') next = addSkillCompanion(next, item.skill, item.relPath)
+        break
+      case 'companion-missing':
+        if (resolution.action === 'remove') next = removeSkillCompanion(next, item.skill, item.relPath)
+        break
+      case 'root-addition':
+        if (resolution.action === 'add') next = addTopLevelFile(next, item.path)
+        break
+      case 'root-missing':
+        if (resolution.action === 'remove') next = removeTopLevelFile(next, item.path)
+        break
+      // asset-* items are reflected through the form / operation list.
+    }
+  }
+  return next
+}
+
+/** Builds the queued operation list from resolutions + form asset changes. */
 function buildOperations(
   context: EditContext,
   form: FormState,
-  resolutions: Map<string, ReconciliationResolution>,
+  resolved: ResolvedItem[],
+  finalManifest: FacetManifest,
 ): EditOperation[] {
-  const operations: EditOperation[] = [{ op: 'write-manifest' }]
-
-  // Operations from reconciliation resolutions
-  for (const [key, resolution] of resolutions) {
-    const parts = key.split(':')
-    const assetType = parts[1] as 'skills' | 'agents' | 'commands'
-    const name = parts[2]
-    if (!assetType || !name) continue
+  const operations: EditOperation[] = [{ op: 'write-manifest', manifest: finalManifest }]
 
-    if (resolution.action === 'scaffold-template') {
-      operations.push({ op: 'scaffold', type: assetType, name })
+  // Supplementary + asset scaffolds driven by reconciliation resolutions.
+  for (const { item, resolution } of resolved) {
+    if (item.kind === 'asset-missing' && resolution.action === 'scaffold') {
+      operations.push({ op: 'scaffold-asset', assetType: item.assetType, name: item.name })
+    }
+    // Missing supplementary files scaffold as empty bytes (valid content).
+    if (item.kind === 'companion-missing' && resolution.action === 'scaffold') {
+      operations.push({ op: 'write-file', path: item.expectedPath, content: '' })
+    }
+    if (item.kind === 'root-missing' && resolution.action === 'scaffold') {
+      operations.push({ op: 'write-file', path: item.path, content: '' })
     }
   }
 
-  // New assets added during editing (not from reconciliation)
+  // Names already present on disk (discovered additions) MUST NOT be scaffolded
+  // over — that would overwrite an existing file with a template.
+  const onDiskAssetNames = new Set(
+    context.reconciliationItems
+      .filter((i): i is Extract<ReconciliationItem, { kind: 'asset-addition' }> => i.kind === 'asset-addition')
+      .map((i) => `${i.assetType}:${i.name}`),
+  )
+
   for (const [formKey, manifestKey] of Object.entries(FORM_TO_MANIFEST) as [
     AssetSectionKey,
     'skills' | 'agents' | 'commands',
   ][]) {
-    const originalSection = context.manifest[manifestKey]
-    const originalNames =
-      originalSection && typeof originalSection === 'object' && !Array.isArray(originalSection)
-        ? Object.keys(originalSection)
-        : []
+    const originalNames = Object.keys(context.manifest[manifestKey] ?? {})
 
+    // Genuinely new assets added in the form → scaffold a starter file.
     for (const name of form.assets[formKey].items) {
-      const isFromReconciliation = resolutions.has(`addition:${manifestKey}:${name}`)
-      if (!originalNames.includes(name) && !isFromReconciliation) {
-        operations.push({ op: 'scaffold', type: manifestKey, name })
-      }
+      if (originalNames.includes(name)) continue
+      if (onDiskAssetNames.has(`${manifestKey}:${name}`)) continue
+      operations.push({ op: 'scaffold-asset', assetType: manifestKey, name })
     }
 
-    // Removed assets
+    // Removed assets → delete the primary and any declared companions (skills).
     for (const name of originalNames) {
-      if (!form.assets[formKey].items.includes(name)) {
-        operations.push({ op: 'delete-file', type: manifestKey, name })
-      }
+      if (form.assets[formKey].items.includes(name)) continue
+      const companionPaths =
+        manifestKey === 'skills'
+          ? (context.manifest.skills?.[name]?.files ?? []).map((rel) => `skills/${name}/${rel}`)
+          : []
+      operations.push({ op: 'delete-asset', assetType: manifestKey, name, companionPaths })
     }
   }
 
   return operations
 }
 
-export function useEditSession(context: EditContext) {
-  const [resolutions, setResolutions] = useState<Map<string, ReconciliationResolution>>(new Map())
+export function useEditSession(context: EditContext, initialResolutions?: Map<string, ResolvedItem>) {
+  const [resolutions, setResolutions] = useState<Map<string, ResolvedItem>>(() => new Map(initialResolutions))
 
-  const resolve = useCallback((key: string, resolution: ReconciliationResolution) => {
+  const resolve = useCallback((item: ReconciliationItem, resolution: ReconciliationResolution) => {
     setResolutions((prev) => {
       const next = new Map(prev)
-      next.set(key, resolution)
+      next.set(reconciliationItemKey(item), { item, resolution })
       return next
     })
   }, [])
 
-  /** Builds the final edit result from current form state and resolutions. */
   const buildResult = useCallback(
     (form: FormState): EditResult => {
-      const manifest = buildManifest(context.manifest, form)
-      const operations = buildOperations(context, form, resolutions)
-      return { outcome: 'applied', manifest, operations }
+      const resolved = Array.from(resolutions.values())
+      const finalManifest = applySupplementaryDeltas(buildManifest(context.manifest, form), resolved)
+      const operations = buildOperations(context, form, resolved, finalManifest)
+      return { outcome: 'applied', operations }
     },
     [context, resolutions],
   )
diff --git a/packages/cli/src/tui/views/edit/wizard.tsx b/packages/cli/src/tui/views/edit/wizard.tsx
index 6e35bc0e..e1bed740 100644
--- a/packages/cli/src/tui/views/edit/wizard.tsx
+++ b/packages/cli/src/tui/views/edit/wizard.tsx
@@ -1,4 +1,4 @@
-import type { EditContext, EditOperation, EditResult, ReconciliationResolution } from '@agent-facets/engine'
+import type { EditContext, EditOperation, EditResult } from '@agent-facets/engine'
 import { useApp } from 'ink'
 import { useCallback, useEffect, useMemo, useState } from 'react'
 import { FocusModeProvider, useFocusMode } from '../../context/focus-mode-context.ts'
@@ -12,7 +12,7 @@ import { EditView } from './edit-view.tsx'
 import { manifestToFormState } from './manifest-to-form.ts'
 import { ReconciliationView } from './reconciliation-view.tsx'
 import { EditSuccessView } from './success-view.tsx'
-import { useEditSession } from './use-edit-session.ts'
+import { type ResolvedItem, useEditSession } from './use-edit-session.ts'
 
 type EditPhase = 'reconciliation' | 'editing' | 'confirmation' | 'done'
 
@@ -20,7 +20,7 @@ export interface EditWizardSnapshot {
   phase: EditPhase
   formState?: FormState
   focusedId?: string | null
-  resolutions: Map<string, ReconciliationResolution>
+  resolutions: Map<string, ResolvedItem>
   selectedItem?: {
     section: AssetSectionKey
     name: string
@@ -58,7 +58,9 @@ function EditWizardInner({
   const initialPhase = snapshot?.phase ?? (hasReconciliation ? 'reconciliation' : 'editing')
   const [phase, setPhase] = useState<EditPhase>(initialPhase)
   const [doneOperations, setDoneOperations] = useState<EditOperation[]>([])
-  const { resolutions, resolve, buildResult } = useEditSession(context)
+  // Seed from the snapshot so resolutions survive external-editor round-trips
+  // (which unmount and remount the wizard).
+  const { resolutions, resolve, buildResult } = useEditSession(context, snapshot?.resolutions)
 
   // Report snapshot to parent for editor round-trips
   useEffect(() => {
@@ -130,8 +132,11 @@ function EditWizardInner({
   }
 
   if (phase === 'confirmation') {
+    const pending = buildResult(form)
+    const operations = pending.outcome === 'applied' ? pending.operations : []
     return (
       <EditConfirmView
+        operations={operations}
         onConfirm={handleConfirm}
         onBack={() => {
           setPhase('editing')
diff --git a/packages/engine/src/__tests__/edit-supplementary.test.ts b/packages/engine/src/__tests__/edit-supplementary.test.ts
new file mode 100644
index 00000000..5cd37fb2
--- /dev/null
+++ b/packages/engine/src/__tests__/edit-supplementary.test.ts
@@ -0,0 +1,247 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
+import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs'
+import { mkdir } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import type { FacetManifest } from '@agent-facets/protocol'
+import { buildEditContext } from '../edit/context.ts'
+import { addSkillCompanion, addTopLevelFile, removeSkillCompanion, removeTopLevelFile } from '../edit/declarations.ts'
+import { previewEditOperations } from '../edit/operation-preview.ts'
+import { applyEditOperations } from '../edit/operations.ts'
+import { computeReadmeStates } from '../edit/readme-state.ts'
+import { reconcileSupplementary } from '../edit/reconcile-supplementary.ts'
+import { scanCommonRootFiles, scanSkillCompanions } from '../edit/scanner.ts'
+import type { EditOperation } from '../edit/types.ts'
+
+let dir: string
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), 'facet-edit-supp-'))
+})
+afterEach(() => {
+  rmSync(dir, { recursive: true, force: true })
+})
+
+async function writeFile(rel: string, content = 'x'): Promise<void> {
+  await mkdir(join(dir, rel, '..'), { recursive: true })
+  await Bun.write(join(dir, rel), content)
+}
+
+// --- Scanner ---
+
+describe('scanSkillCompanions', () => {
+  test('lists nested companions and excludes SKILL.md', async () => {
+    await writeFile('skills/review/SKILL.md', '# Review')
+    await writeFile('skills/review/references/api.md', '# API')
+    await writeFile('skills/review/scripts/run.ts', 'run')
+    const companions = await scanSkillCompanions(dir, 'review')
+    expect(companions).toEqual(['references/api.md', 'scripts/run.ts'])
+  })
+})
+
+describe('scanCommonRootFiles', () => {
+  test('detects present common files and never README', async () => {
+    await writeFile('LICENSE', 'MIT')
+    await writeFile('README.md', '# readme')
+    const files = await scanCommonRootFiles(dir)
+    expect(files).toContain('LICENSE')
+    expect(files).not.toContain('README.md')
+  })
+})
+
+// --- Supplementary reconciliation ---
+
+describe('reconcileSupplementary', () => {
+  const manifest: FacetManifest = {
+    name: 'test',
+    version: '1.0.0',
+    skills: { review: { description: 'Review', files: ['references/api.md'] } },
+    files: ['LICENSE', 'docs/guide.md'],
+  }
+
+  test('flags undeclared companions and declared-missing companions', () => {
+    const items = reconcileSupplementary(manifest, {
+      companionsBySkill: { review: ['scripts/run.ts'] }, // api.md missing, run.ts undeclared
+      presentRootFiles: ['LICENSE', 'docs/guide.md'],
+    })
+    expect(items).toContainEqual({
+      kind: 'companion-addition',
+      skill: 'review',
+      relPath: 'scripts/run.ts',
+      path: 'skills/review/scripts/run.ts',
+    })
+    expect(items).toContainEqual({
+      kind: 'companion-missing',
+      skill: 'review',
+      relPath: 'references/api.md',
+      expectedPath: 'skills/review/references/api.md',
+    })
+  })
+
+  test('flags undeclared common root files and declared-missing root files', () => {
+    const items = reconcileSupplementary(manifest, {
+      companionsBySkill: { review: ['references/api.md'] },
+      presentRootFiles: ['CONTRIBUTING.md'], // LICENSE + docs/guide.md declared but absent; CONTRIBUTING undeclared
+    })
+    expect(items).toContainEqual({ kind: 'root-addition', path: 'CONTRIBUTING.md' })
+    expect(items).toContainEqual({ kind: 'root-missing', path: 'LICENSE' })
+    expect(items).toContainEqual({ kind: 'root-missing', path: 'docs/guide.md' })
+  })
+})
+
+// --- README states ---
+
+describe('computeReadmeStates', () => {
+  test('classifies each conventional path independently', () => {
+    const manifest: FacetManifest = { name: 't', version: '1.0.0', files: ['README.md'] }
+    const states = computeReadmeStates(manifest, { present: { 'README.md': '# hi' } })
+    const md = states.find((s) => s.path === 'README.md')
+    const plain = states.find((s) => s.path === 'README')
+    expect(md?.state).toBe('present-declared')
+    expect(plain?.state).toBe('absent-undeclared')
+  })
+
+  test('present-undeclared and declared-missing', () => {
+    const manifest: FacetManifest = { name: 't', version: '1.0.0', files: ['README'] }
+    const states = computeReadmeStates(manifest, { present: { 'README.md': 'x' } })
+    expect(states.find((s) => s.path === 'README.md')?.state).toBe('present-undeclared')
+    expect(states.find((s) => s.path === 'README')?.state).toBe('declared-missing')
+  })
+})
+
+// --- Declaration mutations ---
+
+describe('declaration mutations', () => {
+  const base: FacetManifest = {
+    name: 't',
+    version: '1.0.0',
+    skills: { review: { description: 'R' } },
+  }
+
+  test('addTopLevelFile keeps files sorted and de-duplicated', () => {
+    let m = addTopLevelFile(base, 'README.md')
+    m = addTopLevelFile(m, 'LICENSE')
+    m = addTopLevelFile(m, 'LICENSE')
+    expect(m.files).toEqual(['LICENSE', 'README.md'])
+  })
+
+  test('removeTopLevelFile drops the files key when empty', () => {
+    const m = removeTopLevelFile(addTopLevelFile(base, 'README.md'), 'README.md')
+    expect('files' in m).toBe(false)
+  })
+
+  test('add/removeSkillCompanion mutate the owning skill only', () => {
+    const added = addSkillCompanion(base, 'review', 'references/api.md')
+    expect(added.skills?.review?.files).toEqual(['references/api.md'])
+    const removed = removeSkillCompanion(added, 'review', 'references/api.md')
+    expect('files' in (removed.skills?.review ?? {})).toBe(false)
+  })
+})
+
+// --- Transactional apply ---
+
+describe('applyEditOperations', () => {
+  const manifest: FacetManifest = {
+    name: 'test',
+    version: '1.0.0',
+    skills: { review: { description: 'R', files: ['references/api.md'] } },
+  }
+
+  test('scaffolds assets and writes supplementary files atomically', async () => {
+    const ops: EditOperation[] = [
+      { op: 'write-manifest', manifest },
+      { op: 'scaffold-asset', assetType: 'skills', name: 'review' },
+      { op: 'write-file', path: 'LICENSE', content: '' },
+    ]
+    const result = await applyEditOperations(ops, dir)
+    expect(result.ok).toBe(true)
+    expect(existsSync(join(dir, 'facet.json'))).toBe(true)
+    expect(existsSync(join(dir, 'skills/review/SKILL.md'))).toBe(true)
+    expect(readFileSync(join(dir, 'LICENSE'), 'utf8')).toBe('')
+  })
+
+  test('delete-asset removes primary and declared companions, preserves unowned files', async () => {
+    await writeFile('skills/review/SKILL.md', '# R')
+    await writeFile('skills/review/references/api.md', '# API')
+    await writeFile('skills/review/notes.txt', 'unowned')
+    const ops: EditOperation[] = [
+      { op: 'write-manifest', manifest: { name: 'test', version: '1.0.0' } },
+      { op: 'delete-asset', assetType: 'skills', name: 'review', companionPaths: ['skills/review/references/api.md'] },
+    ]
+    const result = await applyEditOperations(ops, dir)
+    expect(result.ok).toBe(true)
+    expect(existsSync(join(dir, 'skills/review/SKILL.md'))).toBe(false)
+    expect(existsSync(join(dir, 'skills/review/references/api.md'))).toBe(false)
+    // Undeclared file survives.
+    expect(existsSync(join(dir, 'skills/review/notes.txt'))).toBe(true)
+  })
+
+  test('rolls back every mutation when one write fails', async () => {
+    await writeFile('facet.json', 'ORIGINAL')
+    // Make skills a file so the SKILL.md write fails mid-transaction.
+    await writeFile('skills', 'not a dir')
+    const ops: EditOperation[] = [
+      { op: 'write-manifest', manifest },
+      { op: 'scaffold-asset', assetType: 'skills', name: 'review' },
+    ]
+    const result = await applyEditOperations(ops, dir)
+    expect(result.ok).toBe(false)
+    if (result.ok) expect.unreachable()
+    expect(result.rollbackOk).toBe(true)
+    expect(readFileSync(join(dir, 'facet.json'), 'utf8')).toBe('ORIGINAL')
+  })
+})
+
+// --- Operation preview ---
+
+describe('previewEditOperations', () => {
+  test('lists exact paths including each deleted companion', () => {
+    const lines = previewEditOperations([
+      { op: 'write-manifest', manifest: { name: 't', version: '1.0.0' } },
+      { op: 'delete-asset', assetType: 'skills', name: 'review', companionPaths: ['skills/review/references/api.md'] },
+      { op: 'write-file', path: 'README.md', content: '# hi' },
+    ])
+    expect(lines).toEqual([
+      { verb: 'Update', path: 'facet.json' },
+      { verb: 'Delete', path: 'skills/review/SKILL.md' },
+      { verb: 'Delete', path: 'skills/review/references/api.md' },
+      { verb: 'Write', path: 'README.md' },
+    ])
+  })
+})
+
+// --- Context integration ---
+
+describe('buildEditContext supplementary + README', () => {
+  test('discovers companions, common root files, and routes README to the panel only', async () => {
+    await writeFile(
+      'facet.json',
+      JSON.stringify({
+        name: 'test',
+        version: '1.0.0',
+        skills: { review: { description: 'R' } },
+        files: ['README.md'],
+      }),
+    )
+    await writeFile('skills/review/SKILL.md', '# Review')
+    await writeFile('skills/review/references/api.md', '# API') // undeclared companion
+    await writeFile('LICENSE', 'MIT') // undeclared common root file
+    await writeFile('README.md', '# readme') // declared → README panel, not generic
+
+    const result = await buildEditContext(dir)
+    expect(result.ok).toBe(true)
+    if (!result.ok) expect.unreachable()
+    const { reconciliationItems, readme } = result.context
+
+    expect(reconciliationItems).toContainEqual({
+      kind: 'companion-addition',
+      skill: 'review',
+      relPath: 'references/api.md',
+      path: 'skills/review/references/api.md',
+    })
+    expect(reconciliationItems).toContainEqual({ kind: 'root-addition', path: 'LICENSE' })
+    // README never appears in generic reconciliation.
+    expect(reconciliationItems.some((i) => i.kind === 'root-addition' && i.path === 'README.md')).toBe(false)
+    // README is surfaced via the dedicated panel state.
+    expect(readme.find((s) => s.path === 'README.md')?.state).toBe('present-declared')
+  })
+})
diff --git a/packages/engine/src/edit/context.ts b/packages/engine/src/edit/context.ts
index 8253fffb..142e758f 100644
--- a/packages/engine/src/edit/context.ts
+++ b/packages/engine/src/edit/context.ts
@@ -1,21 +1,23 @@
 import { loadManifest } from '../loaders/facet.ts'
+import { isReadmePath, README_PATHS, type ReadmePath } from '../readme.ts'
+import { computeReadmeStates } from './readme-state.ts'
 import { reconcile } from './reconcile.ts'
-import { scanAssets } from './scanner.ts'
+import { reconcileSupplementary, type SupplementaryDiscovery } from './reconcile-supplementary.ts'
+import { scanAssets, scanCommonRootFiles, scanSkillCompanions } from './scanner.ts'
 import type { EditContext, ReconciliationItem } from './types.ts'
 
 /**
- * Load a facet manifest, scan its assets, and reconcile manifest ↔ disk into
- * a list of items that need user resolution. The CLI passes a callback that
- * routes errors to stderr; tests can pass a no-op or array collector.
+ * Load a facet manifest, scan its assets and supplementary files, and reconcile
+ * manifest ↔ disk into the list of items needing user resolution plus the two
+ * independent README panel states. The CLI passes a callback that routes errors
+ * to stderr; tests can pass a no-op or array collector.
  */
 export async function buildEditContext(
   rootDir: string,
   opts: { onError?: (line: string) => void } = {},
 ): Promise<{ ok: true; context: EditContext } | { ok: false; exitCode: number }> {
-  // Load manifest
   const loadResult = await loadManifest(rootDir)
   if (!loadResult.ok) {
-    // Hard error — surface details and bail
     opts.onError?.('Manifest is invalid:')
     for (const err of loadResult.errors) {
       opts.onError?.(`  ${err.message}`)
@@ -26,26 +28,58 @@ export async function buildEditContext(
 
   const manifest = loadResult.data
 
-  // Scan disk for assets
+  // Conventional primary assets: reconcile disk against manifest declarations.
   const discovered = await scanAssets(rootDir)
+  const assetRecon = reconcile(manifest, discovered)
 
-  // Run reconciliation
-  const recon = reconcile(manifest, discovered)
-
-  // Build reconciliation items
   const items: ReconciliationItem[] = []
+  for (const addition of assetRecon.additions) {
+    items.push({ kind: 'asset-addition', assetType: addition.type, name: addition.name, path: addition.path })
+  }
+  for (const missing of assetRecon.missing) {
+    items.push({
+      kind: 'asset-missing',
+      assetType: missing.type,
+      name: missing.name,
+      expectedPath: missing.expectedPath,
+    })
+  }
+  // Matched assets are not inspected. Author-supplied front matter in matched
+  // files is permitted and reconciled at install time, not at edit time.
 
-  for (const addition of recon.additions) {
-    items.push({ kind: 'addition', type: addition.type, name: addition.name, path: addition.path })
+  // Supplementary files: companions under declared skills + common/declared
+  // top-level files (README excluded, routed to the README panel below).
+  const companionsBySkill: Record<string, string[]> = {}
+  for (const skill of Object.keys(manifest.skills ?? {})) {
+    companionsBySkill[skill] = await scanSkillCompanions(rootDir, skill)
   }
+  const presentRootFiles = await computePresentRootFiles(rootDir, manifest.files ?? [])
+  const disc: SupplementaryDiscovery = { companionsBySkill, presentRootFiles }
+  items.push(...reconcileSupplementary(manifest, disc))
 
-  for (const missing of recon.missing) {
-    items.push({ kind: 'missing', type: missing.type, name: missing.name, expectedPath: missing.expectedPath })
+  // README panel: read each conventional path that exists.
+  const present: Partial<Record<ReadmePath, string>> = {}
+  for (const path of README_PATHS) {
+    const file = Bun.file(`${rootDir}/${path}`)
+    if (await file.exists()) present[path] = await file.text()
   }
+  const readme = computeReadmeStates(manifest, { present })
 
-  // Matched assets are not inspected. Author-supplied front matter in
-  // matched files is permitted and reconciled at install time, not at
-  // edit time — see `materialize` and the SDK's `assembleAssetContent`.
+  return { ok: true, context: { rootDir, manifest, reconciliationItems: items, readme } }
+}
 
-  return { ok: true, context: { rootDir, manifest, reconciliationItems: items } }
+/**
+ * The set of top-level repo-relative paths present on disk that are candidates
+ * for reconciliation: present common root files plus present declared top-level
+ * files. README paths are excluded.
+ */
+async function computePresentRootFiles(rootDir: string, declaredFiles: string[]): Promise<string[]> {
+  const present = new Set(await scanCommonRootFiles(rootDir))
+  for (const path of declaredFiles) {
+    if (isReadmePath(path)) continue
+    // Only top-level declarations belong here; skill companions live under skills/.
+    if (path.startsWith('skills/')) continue
+    if (await Bun.file(`${rootDir}/${path}`).exists()) present.add(path)
+  }
+  return Array.from(present).sort()
 }
diff --git a/packages/engine/src/edit/declarations.ts b/packages/engine/src/edit/declarations.ts
new file mode 100644
index 00000000..a759a956
--- /dev/null
+++ b/packages/engine/src/edit/declarations.ts
@@ -0,0 +1,52 @@
+import type { FacetManifest } from '@agent-facets/protocol'
+
+/**
+ * Pure manifest mutations for supplementary-file declarations. Each returns a
+ * new manifest; `files` arrays are kept sorted and de-duplicated so repeated
+ * edits produce stable, reviewable diffs. Empty arrays are dropped so the
+ * manifest never carries an inert `files: []`.
+ */
+
+function withSortedFiles(files: string[]): string[] {
+  return Array.from(new Set(files)).sort()
+}
+
+/** Add a top-level supplementary declaration (e.g. `README.md`, `LICENSE`). */
+export function addTopLevelFile(manifest: FacetManifest, path: string): FacetManifest {
+  const files = withSortedFiles([...(manifest.files ?? []), path])
+  return { ...manifest, files }
+}
+
+/** Remove a top-level supplementary declaration. Drops `files` if it empties. */
+export function removeTopLevelFile(manifest: FacetManifest, path: string): FacetManifest {
+  const files = (manifest.files ?? []).filter((p) => p !== path)
+  const next = { ...manifest }
+  if (files.length > 0) next.files = withSortedFiles(files)
+  else delete next.files
+  return next
+}
+
+/** Add a companion declaration (relative to the skill dir) to a skill. */
+export function addSkillCompanion(manifest: FacetManifest, skill: string, relPath: string): FacetManifest {
+  const descriptor = manifest.skills?.[skill]
+  if (!descriptor) return manifest
+  const files = withSortedFiles([...(descriptor.files ?? []), relPath])
+  return {
+    ...manifest,
+    skills: { ...manifest.skills, [skill]: { ...descriptor, files } },
+  }
+}
+
+/** Remove a companion declaration from a skill. Drops the skill `files` if empty. */
+export function removeSkillCompanion(manifest: FacetManifest, skill: string, relPath: string): FacetManifest {
+  const descriptor = manifest.skills?.[skill]
+  if (!descriptor) return manifest
+  const files = (descriptor.files ?? []).filter((p) => p !== relPath)
+  const nextDescriptor = { ...descriptor }
+  if (files.length > 0) nextDescriptor.files = withSortedFiles(files)
+  else delete nextDescriptor.files
+  return {
+    ...manifest,
+    skills: { ...manifest.skills, [skill]: nextDescriptor },
+  }
+}
diff --git a/packages/engine/src/edit/operation-preview.ts b/packages/engine/src/edit/operation-preview.ts
new file mode 100644
index 00000000..d8507a2d
--- /dev/null
+++ b/packages/engine/src/edit/operation-preview.ts
@@ -0,0 +1,45 @@
+import { FACET_MANIFEST_FILE } from '@agent-facets/protocol'
+import type { AssetManifestKey } from './scanner.ts'
+import type { EditOperation } from './types.ts'
+
+/** One preview line for a queued edit operation, with its exact repo-relative path. */
+export interface OperationPreviewLine {
+  verb: 'Update' | 'Scaffold' | 'Write' | 'Delete'
+  path: string
+}
+
+/** Conventional primary path (repo-relative) for an asset. */
+function primaryPath(type: AssetManifestKey, name: string): string {
+  return type === 'skills' ? `skills/${name}/SKILL.md` : `${type}/${name}.md`
+}
+
+/**
+ * Expand a queued operation list into exact-path preview lines for the
+ * confirmation and success views. Every file the apply will touch — including
+ * each deleted companion — is listed with its exact path (design D11 "show every
+ * queued exact-path operation before Apply").
+ */
+export function previewEditOperations(operations: EditOperation[]): OperationPreviewLine[] {
+  const lines: OperationPreviewLine[] = []
+  for (const op of operations) {
+    switch (op.op) {
+      case 'write-manifest':
+        lines.push({ verb: 'Update', path: FACET_MANIFEST_FILE })
+        break
+      case 'scaffold-asset':
+        lines.push({ verb: 'Scaffold', path: primaryPath(op.assetType, op.name) })
+        break
+      case 'delete-asset':
+        lines.push({ verb: 'Delete', path: primaryPath(op.assetType, op.name) })
+        for (const companion of op.companionPaths) lines.push({ verb: 'Delete', path: companion })
+        break
+      case 'write-file':
+        lines.push({ verb: 'Write', path: op.path })
+        break
+      case 'delete-file':
+        lines.push({ verb: 'Delete', path: op.path })
+        break
+    }
+  }
+  return lines
+}
diff --git a/packages/engine/src/edit/operations.ts b/packages/engine/src/edit/operations.ts
index 20a039a6..cb635ef7 100644
--- a/packages/engine/src/edit/operations.ts
+++ b/packages/engine/src/edit/operations.ts
@@ -1,40 +1,79 @@
 import { mkdir, rename, rmdir, unlink } from 'node:fs/promises'
 import { dirname, join } from 'node:path'
-import type { FacetManifest } from '@agent-facets/protocol'
+import { FACET_MANIFEST_FILE } from '@agent-facets/protocol'
+import { applyFsTransaction, type FsMutation } from '../fs-transaction.ts'
+import { jsonFileText } from '../json-file-text.ts'
 import { agentTemplate, commandTemplate, skillTemplate } from '../scaffold/index.ts'
 import type { ModifyFileOp } from './apply-modify.ts'
-import { writeManifest } from './manifest-writer.ts'
 import type { AssetManifestKey } from './scanner.ts'
 import type { EditOperation } from './types.ts'
 
+/** Result of a transactional edit apply. Expected failures are data, not throws. */
+export type EditApplyResult = { ok: true } | { ok: false; failedPath: string; reason: string; rollbackOk: boolean }
+
 /**
- * Apply a sequence of edit operations to disk: write the manifest, scaffold
- * new asset templates, and delete files.
+ * Apply a queued edit-operation list to disk as one transaction: the final
+ * manifest, asset scaffolds, asset/companion/file writes and deletions all
+ * commit together, or the project is left as it was. Ordering the manifest
+ * write alongside the file mutations in one transaction removes the old hazard
+ * where a manifest could be written before a failing scaffold.
  */
-export async function applyEditOperations(
-  manifest: FacetManifest,
-  operations: EditOperation[],
-  rootDir: string,
-): Promise<void> {
+export async function applyEditOperations(operations: EditOperation[], rootDir: string): Promise<EditApplyResult> {
+  const encoder = new TextEncoder()
+  const mutations: FsMutation[] = []
+
   for (const op of operations) {
     switch (op.op) {
       case 'write-manifest':
-        await writeManifest(manifest, rootDir)
+        mutations.push({
+          kind: 'write',
+          path: join(rootDir, FACET_MANIFEST_FILE),
+          bytes: encoder.encode(jsonFileText(op.manifest)),
+        })
         break
-      case 'scaffold':
-        await scaffoldAsset(rootDir, op.type, op.name)
+      case 'scaffold-asset': {
+        const { path, content } = assetScaffoldTarget(rootDir, op.assetType, op.name)
+        mutations.push({ kind: 'write', path, bytes: encoder.encode(content) })
+        break
+      }
+      case 'delete-asset': {
+        mutations.push({ kind: 'delete', path: assetPrimaryPath(rootDir, op.assetType, op.name) })
+        for (const companion of op.companionPaths) {
+          mutations.push({ kind: 'delete', path: join(rootDir, companion) })
+        }
+        break
+      }
+      case 'write-file':
+        mutations.push({ kind: 'write', path: join(rootDir, op.path), bytes: encoder.encode(op.content) })
         break
       case 'delete-file':
-        await deleteAsset(rootDir, op.type, op.name)
+        mutations.push({ kind: 'delete', path: join(rootDir, op.path) })
         break
     }
   }
+
+  const result = applyFsTransaction(mutations)
+  if (result.ok) return { ok: true }
+  return { ok: false, failedPath: result.failedPath, reason: result.reason, rollbackOk: result.rollback.ok }
+}
+
+/** Conventional primary path for an asset (absolute). */
+function assetPrimaryPath(rootDir: string, type: AssetManifestKey, name: string): string {
+  return type === 'skills' ? join(rootDir, 'skills', name, 'SKILL.md') : join(rootDir, type, `${name}.md`)
+}
+
+/** Conventional primary path + starter template for a scaffolded asset. */
+function assetScaffoldTarget(rootDir: string, type: AssetManifestKey, name: string): { path: string; content: string } {
+  if (type === 'skills') return { path: join(rootDir, 'skills', name, 'SKILL.md'), content: skillTemplate(name) }
+  if (type === 'agents') return { path: join(rootDir, 'agents', `${name}.md`), content: agentTemplate(name) }
+  return { path: join(rootDir, 'commands', `${name}.md`), content: commandTemplate(name) }
 }
 
 /**
  * Apply the filesystem side effects computed by `applyModify` (scaffold new
  * asset templates, delete removed assets, move renamed asset files). The
- * manifest itself is written separately by the caller.
+ * manifest itself is written separately by the caller. This is the flag-driven
+ * `facet add`/`facet modify` path, distinct from the interactive edit apply.
  */
 export async function applyModifyFileOps(rootDir: string, fileOps: ModifyFileOp[]): Promise<void> {
   for (const op of fileOps) {
diff --git a/packages/engine/src/edit/readme-state.ts b/packages/engine/src/edit/readme-state.ts
new file mode 100644
index 00000000..12d9d182
--- /dev/null
+++ b/packages/engine/src/edit/readme-state.ts
@@ -0,0 +1,27 @@
+import type { FacetManifest } from '@agent-facets/protocol'
+import { README_PATHS, type ReadmePath } from '../readme.ts'
+import type { ReadmeFileState } from './types.ts'
+
+/** On-disk facts for the two conventional README paths. */
+export interface ReadmeDiskFacts {
+  /** Decoded text content for each README path that exists on disk. */
+  present: Partial<Record<ReadmePath, string>>
+}
+
+/**
+ * Derive one independent state per conventional README path from the manifest's
+ * top-level `files` declarations and disk presence. Each path is classified
+ * exactly once into one of the four tagged states; there is no representable
+ * "present and absent" combination.
+ */
+export function computeReadmeStates(manifest: FacetManifest, facts: ReadmeDiskFacts): ReadmeFileState[] {
+  const declaredFiles = new Set(manifest.files ?? [])
+  return README_PATHS.map((path): ReadmeFileState => {
+    const isDeclared = declaredFiles.has(path)
+    const content = facts.present[path]
+    if (content !== undefined) {
+      return isDeclared ? { path, state: 'present-declared', content } : { path, state: 'present-undeclared', content }
+    }
+    return isDeclared ? { path, state: 'declared-missing' } : { path, state: 'absent-undeclared' }
+  })
+}
diff --git a/packages/engine/src/edit/reconcile-actions.ts b/packages/engine/src/edit/reconcile-actions.ts
new file mode 100644
index 00000000..bb4c2c37
--- /dev/null
+++ b/packages/engine/src/edit/reconcile-actions.ts
@@ -0,0 +1,54 @@
+import type { ReconciliationItem, ReconciliationResolution } from './types.ts'
+
+/**
+ * Correlation logic between a reconciliation item and its legal actions, and a
+ * one-way stable identity key. Centralized so the two legal actions per item
+ * and the item→resolution mapping have a single source of truth, and so illegal
+ * item/action pairings (e.g. `remove` on an addition) are never constructed.
+ *
+ * `reconciliationItemKey` is a *rendering/lookup* key only — it is never parsed
+ * back into fields. Business logic carries the structured item itself.
+ */
+
+/** True for the three "found on disk, not declared" variants. */
+export function isAdditionItem(item: ReconciliationItem): boolean {
+  return item.kind === 'asset-addition' || item.kind === 'companion-addition' || item.kind === 'root-addition'
+}
+
+/** The two option labels for an item, in index order. */
+export function optionLabelsFor(item: ReconciliationItem): [string, string] {
+  return isAdditionItem(item) ? ['Add to manifest', 'Ignore for now'] : ['Scaffold template', 'Remove from manifest']
+}
+
+/** The resolution for a chosen option index. Only legal actions are produced. */
+export function resolutionForOption(item: ReconciliationItem, index: number): ReconciliationResolution {
+  if (isAdditionItem(item)) return index === 0 ? { action: 'add' } : { action: 'ignore' }
+  return index === 0 ? { action: 'scaffold' } : { action: 'remove' }
+}
+
+/** The selected option index for a stored resolution, or null if none/invalid. */
+export function optionIndexForResolution(
+  item: ReconciliationItem,
+  resolution: ReconciliationResolution | undefined,
+): number | null {
+  if (!resolution) return null
+  if (isAdditionItem(item)) {
+    return resolution.action === 'add' ? 0 : resolution.action === 'ignore' ? 1 : null
+  }
+  return resolution.action === 'scaffold' ? 0 : resolution.action === 'remove' ? 1 : null
+}
+
+/** A stable, injective, one-way key for React lists and focus ids. Never parsed. */
+export function reconciliationItemKey(item: ReconciliationItem): string {
+  switch (item.kind) {
+    case 'asset-addition':
+    case 'asset-missing':
+      return `asset:${item.assetType}:${item.name}`
+    case 'companion-addition':
+    case 'companion-missing':
+      return `companion:${item.skill}:${item.relPath}`
+    case 'root-addition':
+    case 'root-missing':
+      return `root:${item.path}`
+  }
+}
diff --git a/packages/engine/src/edit/reconcile-supplementary.ts b/packages/engine/src/edit/reconcile-supplementary.ts
new file mode 100644
index 00000000..46c1a299
--- /dev/null
+++ b/packages/engine/src/edit/reconcile-supplementary.ts
@@ -0,0 +1,55 @@
+import type { FacetManifest } from '@agent-facets/protocol'
+import { isReadmePath } from '../readme.ts'
+import type { ReconciliationItem } from './types.ts'
+
+/** Disk facts about supplementary files, gathered by the context builder. */
+export interface SupplementaryDiscovery {
+  /** Declared skill name → companion relPaths present on disk (excludes SKILL.md). */
+  companionsBySkill: Record<string, string[]>
+  /**
+   * Repo-relative top-level paths present on disk that are candidates for
+   * reconciliation: the union of present common root files and present declared
+   * top-level files. README paths are excluded (handled by the README panel).
+   */
+  presentRootFiles: string[]
+}
+
+/**
+ * Pure reconciliation of supplementary declarations against disk facts. Emits
+ * companion additions/missings per declared skill and top-level (root) file
+ * additions/missings, all as structured items. README paths never appear here.
+ */
+export function reconcileSupplementary(manifest: FacetManifest, disc: SupplementaryDiscovery): ReconciliationItem[] {
+  const items: ReconciliationItem[] = []
+
+  // Companions, per declared skill.
+  for (const [skill, descriptor] of Object.entries(manifest.skills ?? {})) {
+    const declared = new Set(descriptor.files ?? [])
+    const onDisk = disc.companionsBySkill[skill] ?? []
+    const onDiskSet = new Set(onDisk)
+    for (const relPath of onDisk) {
+      if (!declared.has(relPath)) {
+        items.push({ kind: 'companion-addition', skill, relPath, path: `skills/${skill}/${relPath}` })
+      }
+    }
+    for (const relPath of declared) {
+      if (!onDiskSet.has(relPath)) {
+        items.push({ kind: 'companion-missing', skill, relPath, expectedPath: `skills/${skill}/${relPath}` })
+      }
+    }
+  }
+
+  // Top-level supplementary files, excluding README (README panel owns those).
+  const present = new Set(disc.presentRootFiles)
+  const declaredFiles = (manifest.files ?? []).filter((p) => !isReadmePath(p))
+  const declaredSet = new Set(declaredFiles)
+  for (const path of declaredFiles) {
+    if (!present.has(path)) items.push({ kind: 'root-missing', path })
+  }
+  for (const path of disc.presentRootFiles) {
+    if (isReadmePath(path)) continue
+    if (!declaredSet.has(path)) items.push({ kind: 'root-addition', path })
+  }
+
+  return items
+}
diff --git a/packages/engine/src/edit/scanner.ts b/packages/engine/src/edit/scanner.ts
index 61cb437b..a8982f8e 100644
--- a/packages/engine/src/edit/scanner.ts
+++ b/packages/engine/src/edit/scanner.ts
@@ -1,5 +1,6 @@
 import type { AssetType } from '@agent-facets/common'
 import { validateAssetNameSegment } from '@agent-facets/protocol'
+import { isReadmePath } from '../readme.ts'
 
 /**
  * Plural manifest key derived from the canonical singular AssetType.
@@ -14,6 +15,21 @@ export interface DiscoveredAsset {
   path: string
 }
 
+/**
+ * Common root-level supplementary files the edit scanner offers to adopt when
+ * present but undeclared. Deliberately a small curated set — arbitrary stray
+ * files are not surfaced (design D11 "SHOULD detect other common root files").
+ * README paths are excluded here and routed to the dedicated README panel.
+ */
+export const COMMON_ROOT_FILES: readonly string[] = [
+  'LICENSE',
+  'LICENSE.md',
+  'LICENSE.txt',
+  'CHANGELOG.md',
+  'CONTRIBUTING.md',
+  'DEVELOPMENT.md',
+] as const
+
 /**
  * Scans a facet directory for content files and returns discovered assets.
  *
@@ -57,3 +73,35 @@ export async function scanAssets(rootDir: string): Promise<DiscoveredAsset[]> {
 
   return assets.sort((a, b) => a.type.localeCompare(b.type) || a.name.localeCompare(b.name))
 }
+
+/**
+ * Scan all regular files beneath a declared skill's directory, excluding the
+ * primary `SKILL.md`, and return their paths relative to the skill directory
+ * (e.g. `references/api.md`). Used to detect undeclared companions and to
+ * confirm declared companions exist on disk.
+ */
+export async function scanSkillCompanions(rootDir: string, skill: string): Promise<string[]> {
+  const glob = new Bun.Glob(`skills/${skill}/**/*`)
+  const rels: string[] = []
+  const prefix = `skills/${skill}/`
+  for await (const match of glob.scan({ cwd: rootDir, onlyFiles: true })) {
+    if (!match.startsWith(prefix)) continue
+    const rel = match.slice(prefix.length)
+    if (rel === 'SKILL.md') continue
+    rels.push(rel)
+  }
+  return rels.sort()
+}
+
+/**
+ * Return the subset of `COMMON_ROOT_FILES` present as regular files at the
+ * project root. README paths are never included.
+ */
+export async function scanCommonRootFiles(rootDir: string): Promise<string[]> {
+  const present: string[] = []
+  for (const name of COMMON_ROOT_FILES) {
+    if (isReadmePath(name)) continue
+    if (await Bun.file(`${rootDir}/${name}`).exists()) present.push(name)
+  }
+  return present
+}
diff --git a/packages/engine/src/edit/types.ts b/packages/engine/src/edit/types.ts
index e07d518f..dd5f97f8 100644
--- a/packages/engine/src/edit/types.ts
+++ b/packages/engine/src/edit/types.ts
@@ -1,32 +1,75 @@
 import type { FacetManifest } from '@agent-facets/protocol'
+import type { ReadmePath } from '../readme.ts'
 import type { AssetManifestKey } from './scanner.ts'
 
-/** A reconciliation item that needs a resolution before editing can proceed. */
+/**
+ * Where a supplementary file is declared. `root` is the manifest's top-level
+ * `files` array (repo-relative paths); `skill` is a skill descriptor's `files`
+ * array (paths relative to that skill's directory).
+ */
+export type DeclarationSite = { kind: 'root' } | { kind: 'skill'; skill: string }
+
+/**
+ * A reconciliation item needing a resolution before editing proceeds. Each
+ * variant carries a structured identity — no colon-joined string that a
+ * consumer must parse back into fields. Path-bearing supplementary variants are
+ * distinct from asset variants so classification never rides on optional
+ * fields. README paths are NEVER represented here; they are handled by the
+ * dedicated README panel (see `ReadmeFileState`).
+ */
 export type ReconciliationItem =
-  | { kind: 'addition'; type: AssetManifestKey; name: string; path: string }
-  | { kind: 'missing'; type: AssetManifestKey; name: string; expectedPath: string }
+  | { kind: 'asset-addition'; assetType: AssetManifestKey; name: string; path: string }
+  | { kind: 'asset-missing'; assetType: AssetManifestKey; name: string; expectedPath: string }
+  | { kind: 'companion-addition'; skill: string; relPath: string; path: string }
+  | { kind: 'companion-missing'; skill: string; relPath: string; expectedPath: string }
+  | { kind: 'root-addition'; path: string }
+  | { kind: 'root-missing'; path: string }
 
-/** The resolution chosen for a reconciliation item. */
+/**
+ * The resolution chosen for a reconciliation item. `add`/`ignore` are the only
+ * legal actions for an *-addition item; `scaffold`/`remove` the only legal
+ * actions for a *-missing item. Resolutions are produced solely by
+ * `resolutionForOption` (see reconcile-actions.ts), so an illegal item/action
+ * pairing is never constructed.
+ */
 export type ReconciliationResolution =
-  | { action: 'add-to-manifest' }
+  | { action: 'add' }
   | { action: 'ignore' }
-  | { action: 'scaffold-template' }
-  | { action: 'remove-from-manifest' }
+  | { action: 'scaffold' }
+  | { action: 'remove' }
+
+/**
+ * State of one conventional README path (`README.md` or `README`), managed
+ * independently in the dedicated README panel. Present states carry the current
+ * on-disk content so the panel can seed the editor; adoption preserves those
+ * bytes by queuing no file write.
+ */
+export type ReadmeFileState =
+  | { path: ReadmePath; state: 'present-declared'; content: string }
+  | { path: ReadmePath; state: 'present-undeclared'; content: string }
+  | { path: ReadmePath; state: 'declared-missing' }
+  | { path: ReadmePath; state: 'absent-undeclared' }
 
 /** All data needed to run the edit TUI. */
 export interface EditContext {
   rootDir: string
   manifest: FacetManifest
   reconciliationItems: ReconciliationItem[]
+  /** Exactly the two conventional README paths, each with its independent state. */
+  readme: ReadmeFileState[]
 }
 
 /** The result of the edit wizard — either applied changes or cancelled. */
-export type EditResult =
-  | { outcome: 'applied'; manifest: FacetManifest; operations: EditOperation[] }
-  | { outcome: 'cancelled' }
+export type EditResult = { outcome: 'applied'; operations: EditOperation[] } | { outcome: 'cancelled' }
 
-/** A file operation to perform on confirmation. */
+/**
+ * A queued edit operation. The final manifest travels inside `write-manifest`
+ * so one operations list drives the whole transactional apply. Every file
+ * operation carries an exact repo-relative path for the confirmation preview.
+ */
 export type EditOperation =
-  | { op: 'write-manifest' }
-  | { op: 'scaffold'; type: AssetManifestKey; name: string }
-  | { op: 'delete-file'; type: AssetManifestKey; name: string }
+  | { op: 'write-manifest'; manifest: FacetManifest }
+  | { op: 'scaffold-asset'; assetType: AssetManifestKey; name: string }
+  | { op: 'delete-asset'; assetType: AssetManifestKey; name: string; companionPaths: string[] }
+  | { op: 'write-file'; path: string; content: string }
+  | { op: 'delete-file'; path: string }
diff --git a/packages/engine/src/fs-transaction.ts b/packages/engine/src/fs-transaction.ts
index 9dbd3687..f01a71fb 100644
--- a/packages/engine/src/fs-transaction.ts
+++ b/packages/engine/src/fs-transaction.ts
@@ -64,7 +64,14 @@ function applyMutation(mutation: FsMutation): void {
 function restorePreimage(preimage: Preimage): void {
   if (!preimage.existed) {
     // Path did not exist before the transaction; ensure it does not exist now.
-    rmSync(preimage.path, { force: true })
+    // `force` swallows ENOENT. If the target still cannot exist (e.g. a parent
+    // is not a directory), it is already effectively absent — best-effort
+    // absence restoration never fails the rollback.
+    try {
+      rmSync(preimage.path, { force: true })
+    } catch {
+      // Already absent for all practical purposes.
+    }
     return
   }
   mkdirSync(dirname(preimage.path), { recursive: true })
diff --git a/packages/engine/src/index.ts b/packages/engine/src/index.ts
index 92a8ad39..ffe64bb5 100644
--- a/packages/engine/src/index.ts
+++ b/packages/engine/src/index.ts
@@ -96,16 +96,34 @@ export type {
 } from './edit/apply-modify.ts'
 export { applyModify, assetPath } from './edit/apply-modify.ts'
 export { buildEditContext } from './edit/context.ts'
+export {
+  addSkillCompanion,
+  addTopLevelFile,
+  removeSkillCompanion,
+  removeTopLevelFile,
+} from './edit/declarations.ts'
 export { writeManifest } from './edit/manifest-writer.ts'
+export type { OperationPreviewLine } from './edit/operation-preview.ts'
+export { previewEditOperations } from './edit/operation-preview.ts'
+export type { EditApplyResult } from './edit/operations.ts'
 export { applyEditOperations, applyModifyFileOps } from './edit/operations.ts'
 export type { MatchedAsset, MissingAsset, ReconciliationResult } from './edit/reconcile.ts'
 export { reconcile } from './edit/reconcile.ts'
+export {
+  isAdditionItem,
+  optionIndexForResolution,
+  optionLabelsFor,
+  reconciliationItemKey,
+  resolutionForOption,
+} from './edit/reconcile-actions.ts'
 export type { AssetManifestKey, DiscoveredAsset } from './edit/scanner.ts'
-export { scanAssets } from './edit/scanner.ts'
+export { COMMON_ROOT_FILES, scanAssets, scanCommonRootFiles, scanSkillCompanions } from './edit/scanner.ts'
 export type {
+  DeclarationSite,
   EditContext,
   EditOperation,
   EditResult,
+  ReadmeFileState,
   ReconciliationItem,
   ReconciliationResolution,
 } from './edit/types.ts'