From d80c6e471999d1536bec6b11a2555bf50e4ff48e Mon Sep 17 00:00:00 2001
From: Julian Coy <julian@ex-machina.co>
Date: Thu, 23 Jul 2026 20:59:12 -0400
Subject: [PATCH 1/2] Add independent tagged README actions, panel view, and
 editor round-trip integration for both conventional paths

---
 .../changes/support-non-asset-files/tasks.md  |   2 +-
 packages/cli/src/commands/edit/wizard.tsx     |  85 ++++---
 .../src/tui/views/edit/readme-panel-view.tsx  | 220 ++++++++++++++++++
 .../src/tui/views/edit/use-edit-session.ts    |  54 ++++-
 packages/cli/src/tui/views/edit/wizard.tsx    |  79 ++++++-
 .../src/__tests__/edit-supplementary.test.ts  |  95 ++++++++
 packages/engine/src/edit/readme-actions.ts    | 177 ++++++++++++++
 packages/engine/src/index.ts                  |  10 +
 8 files changed, 672 insertions(+), 50 deletions(-)
 create mode 100644 packages/cli/src/tui/views/edit/readme-panel-view.tsx
 create mode 100644 packages/engine/src/edit/readme-actions.ts

diff --git a/openspec/changes/support-non-asset-files/tasks.md b/openspec/changes/support-non-asset-files/tasks.md
index b432734d..ef87b2cc 100644
--- a/openspec/changes/support-non-asset-files/tasks.md
+++ b/openspec/changes/support-non-asset-files/tasks.md
@@ -126,7 +126,7 @@
 - [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
 - [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
+- [x] 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
 - [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
diff --git a/packages/cli/src/commands/edit/wizard.tsx b/packages/cli/src/commands/edit/wizard.tsx
index 6687f6a0..7b65faa9 100644
--- a/packages/cli/src/commands/edit/wizard.tsx
+++ b/packages/cli/src/commands/edit/wizard.tsx
@@ -1,16 +1,10 @@
 import type { EditContext, EditResult } from '@agent-facets/engine'
+import { readmeActionFor } from '@agent-facets/engine'
 import { render } from 'ink'
-import type { AssetSectionKey } from '../../tui/context/form-state-context.ts'
 import { openInEditorSync } from '../../tui/editor.ts'
-import type { EditWizardSnapshot } from '../../tui/views/edit/wizard.tsx'
+import type { EditEditorRequest, EditWizardSnapshot } from '../../tui/views/edit/wizard.tsx'
 import { EditWizard } from '../../tui/views/edit/wizard.tsx'
 
-interface EditorRequest {
-  section: AssetSectionKey
-  name: string
-  description: string
-}
-
 export interface RunEditWizardOptions {
   /** Apply edit operations to disk. */
   onApply: (result: EditResult & { outcome: 'applied' }) => Promise<void>
@@ -25,7 +19,7 @@ export interface RunEditWizardOptions {
 export async function runEditWizardInk(context: EditContext, options: RunEditWizardOptions): Promise<boolean> {
   let completed = false
   let snapshot: EditWizardSnapshot | undefined
-  let pendingEditor: EditorRequest | null = null
+  let pendingEditor: EditEditorRequest | null = null
   let done = false
 
   while (!done) {
@@ -44,8 +38,8 @@ export async function runEditWizardInk(context: EditContext, options: RunEditWiz
           onSnapshot={(s) => {
             snapshot = s
           }}
-          onRequestEditor={(section, name, description) => {
-            pendingEditor = { section, name, description }
+          onRequestEditor={(request) => {
+            pendingEditor = request
             instance.clear()
             instance.unmount()
           }}
@@ -56,29 +50,7 @@ export async function runEditWizardInk(context: EditContext, options: RunEditWiz
     })
 
     if (pendingEditor) {
-      const req = pendingEditor as EditorRequest
-      const edited = openInEditorSync(req.description, `${req.name}.md`)
-      if (snapshot) {
-        snapshot = {
-          ...snapshot,
-          selectedItem: undefined,
-          formState: snapshot.formState
-            ? {
-                ...snapshot.formState,
-                assets: {
-                  ...snapshot.formState.assets,
-                  [req.section]: {
-                    ...snapshot.formState.assets[req.section],
-                    descriptions: {
-                      ...snapshot.formState.assets[req.section].descriptions,
-                      ...(edited !== null ? { [req.name]: edited.trim() } : {}),
-                    },
-                  },
-                },
-              }
-            : undefined,
-        }
-      }
+      snapshot = applyEditorRoundTrip(pendingEditor, snapshot)
     } else {
       done = true
     }
@@ -86,3 +58,48 @@ export async function runEditWizardInk(context: EditContext, options: RunEditWiz
 
   return completed
 }
+
+/**
+ * Open the external editor for a pending request and fold the result back into
+ * the wizard snapshot so the re-rendered wizard sees the edit. Asset-description
+ * edits update the form; README edits become the chosen tagged action on the
+ * exact path (bytes discarded → no action, so a cancelled editor leaves the
+ * path untouched rather than queuing empty content).
+ */
+function applyEditorRoundTrip(
+  request: EditEditorRequest,
+  snapshot: EditWizardSnapshot | undefined,
+): EditWizardSnapshot | undefined {
+  if (!snapshot) return snapshot
+
+  if (request.kind === 'asset-description') {
+    const edited = openInEditorSync(request.content, `${request.name}.md`)
+    return {
+      ...snapshot,
+      selectedItem: undefined,
+      formState: snapshot.formState
+        ? {
+            ...snapshot.formState,
+            assets: {
+              ...snapshot.formState.assets,
+              [request.section]: {
+                ...snapshot.formState.assets[request.section],
+                descriptions: {
+                  ...snapshot.formState.assets[request.section].descriptions,
+                  ...(edited !== null ? { [request.name]: edited.trim() } : {}),
+                },
+              },
+            },
+          }
+        : undefined,
+    }
+  }
+
+  // README content edit: seed the editor with the request content, then queue
+  // the tagged action for this path. A cancelled editor (null) queues nothing.
+  const edited = openInEditorSync(request.content, request.path)
+  if (edited === null) return { ...snapshot, selectedItem: undefined }
+  const nextReadme = new Map(snapshot.readmeActions)
+  nextReadme.set(request.path, readmeActionFor(request.option.kind, edited))
+  return { ...snapshot, selectedItem: undefined, readmeActions: nextReadme }
+}
diff --git a/packages/cli/src/tui/views/edit/readme-panel-view.tsx b/packages/cli/src/tui/views/edit/readme-panel-view.tsx
new file mode 100644
index 00000000..734a33e3
--- /dev/null
+++ b/packages/cli/src/tui/views/edit/readme-panel-view.tsx
@@ -0,0 +1,220 @@
+import {
+  type ReadmeAction,
+  type ReadmeActionOption,
+  type ReadmeFileState,
+  type ReadmePath,
+  readmeActionOptions,
+  readmeOptionKindFor,
+} from '@agent-facets/engine'
+import { Box, Text, useInput } from 'ink'
+import Gradient from 'ink-gradient'
+import { useCallback, useEffect, useMemo, useState } from 'react'
+import { Button } from '../../components/button.tsx'
+import { useFocusOrder } from '../../context/focus-order-context.ts'
+import { GRADIENT_STOPS, getAnimatedGradient } from '../../gradient.ts'
+import { THEME } from '../../theme.ts'
+
+const ANIMATION_INTERVAL_MS = 75
+
+/** Human-readable summary of a README path's current on-disk/declaration state. */
+function stateLabel(state: ReadmeFileState): string {
+  switch (state.state) {
+    case 'present-declared':
+      return 'present, declared'
+    case 'present-undeclared':
+      return 'present, not declared'
+    case 'declared-missing':
+      return 'declared, missing on disk'
+    case 'absent-undeclared':
+      return 'absent'
+  }
+}
+
+/**
+ * One README path row. Renders the path, its current state, and its legal
+ * action options (1 or 2 per state). Left/right move the highlight; Enter
+ * selects. Content-bearing options are marked so the parent opens the editor.
+ * `none` (leave as-is) is always available as an implicit first choice so an
+ * author can decline to touch a path.
+ */
+function ReadmeRow({
+  id,
+  state,
+  action,
+  onSelect,
+}: {
+  id: string
+  state: ReadmeFileState
+  action: ReadmeAction | undefined
+  onSelect: (option: ReadmeActionOption) => void
+}) {
+  const { focusedId } = useFocusOrder()
+  const isFocused = focusedId === id
+  const options = useMemo(() => readmeActionOptions(state), [state])
+
+  const selectedKind = action ? readmeOptionKindFor(action) : null
+  const selectedIndex = selectedKind ? options.findIndex((o) => o.kind === selectedKind) : -1
+
+  const [highlightedIndex, setHighlightedIndex] = useState(selectedIndex >= 0 ? selectedIndex : 0)
+  const [offset, setOffset] = useState(0)
+
+  useEffect(() => {
+    if (!isFocused) return
+    const interval = setInterval(() => {
+      setOffset((prev) => (prev + 1) % GRADIENT_STOPS.length)
+    }, ANIMATION_INTERVAL_MS)
+    return () => clearInterval(interval)
+  }, [isFocused])
+
+  useInput(
+    (_input, key) => {
+      if (key.leftArrow) setHighlightedIndex((i) => Math.max(0, i - 1))
+      if (key.rightArrow) setHighlightedIndex((i) => Math.min(options.length - 1, i + 1))
+      if (key.return) {
+        const option = options[highlightedIndex]
+        if (option) onSelect(option)
+      }
+    },
+    { isActive: isFocused },
+  )
+
+  const animatedColors = getAnimatedGradient(offset)
+  const leaveSelected = action === undefined || action.kind === 'none'
+
+  return (
+    <Box flexDirection="column">
+      <Box gap={2}>
+        <Box gap={1}>
+          {isFocused ? (
+            <Text color={THEME.focus} bold>
+              ▸
+            </Text>
+          ) : (
+            <Text> </Text>
+          )}
+          <Text color={isFocused ? THEME.focus : undefined}>{state.path}</Text>
+        </Box>
+
+        <Box gap={2}>
+          {options.map((opt, i) => {
+            const isSelected = selectedIndex === i
+            const isHighlighted = isFocused && highlightedIndex === i
+            if (isHighlighted) {
+              return (
+                <Box key={opt.kind} gap={1}>
+                  {isSelected && <Text color={THEME.success}>✓</Text>}
+                  <Gradient colors={animatedColors}>
+                    <Text bold>{opt.label}</Text>
+                  </Gradient>
+                </Box>
+              )
+            }
+            if (isSelected) {
+              return (
+                <Box key={opt.kind} gap={1}>
+                  <Text color={THEME.success}>✓</Text>
+                  <Gradient colors={[...THEME.gradient]}>
+                    <Text bold>{opt.label}</Text>
+                  </Gradient>
+                </Box>
+              )
+            }
+            return (
+              <Text key={opt.kind} dimColor>
+                {opt.label}
+              </Text>
+            )
+          })}
+        </Box>
+      </Box>
+
+      <Box marginLeft={2}>
+        <Text dimColor>
+          {stateLabel(state)}
+          {leaveSelected ? ' · leaving as-is' : ''}
+        </Text>
+      </Box>
+    </Box>
+  )
+}
+
+/**
+ * The dedicated facet-level README panel (design D11). Shows both conventional
+ * README paths independently, each with its legal actions. Content-bearing
+ * choices request the external editor via `onEditReadme`; all others are queued
+ * immediately via `onResolve`. No disk or manifest change happens here — every
+ * choice is queued until the confirmation Apply.
+ */
+export function ReadmePanelView({
+  states,
+  actions,
+  onResolve,
+  onEditReadme,
+  onContinue,
+}: {
+  states: ReadmeFileState[]
+  actions: Map<ReadmePath, ReadmeAction>
+  onResolve: (path: ReadmePath, option: ReadmeActionOption) => void
+  onEditReadme: (path: ReadmePath, option: ReadmeActionOption) => void
+  onContinue: () => void
+}) {
+  const { setFocusIds, focusedId, focus } = useFocusOrder()
+
+  const focusIds = useMemo(() => {
+    const ids = states.map((s) => `readme-${s.path}`)
+    ids.push('readme-continue')
+    return ids
+  }, [states])
+
+  useEffect(() => {
+    setFocusIds(focusIds)
+    if (!focusedId) focus(focusIds[0] ?? '')
+  }, [focusIds, setFocusIds, focusedId, focus])
+
+  const handleSelect = useCallback(
+    (path: ReadmePath, option: ReadmeActionOption) => {
+      if (option.requiresEditor) {
+        onEditReadme(path, option)
+      } else {
+        onResolve(path, option)
+      }
+      focus('readme-continue')
+    },
+    [onResolve, onEditReadme, focus],
+  )
+
+  return (
+    <Box flexDirection="column">
+      <Text bold color={THEME.brand}>
+        README
+      </Text>
+      <Box marginBottom={0}>
+        <Text dimColor>Manage the conventional README files. Changes apply on the final confirmation.</Text>
+      </Box>
+
+      {states.map((state) => (
+        <ReadmeRow
+          key={state.path}
+          id={`readme-${state.path}`}
+          state={state}
+          action={actions.get(state.path)}
+          onSelect={(option) => handleSelect(state.path, option)}
+        />
+      ))}
+
+      <Box marginTop={1}>
+        <Button
+          id="readme-continue"
+          label="[ Continue to edit ]"
+          gradient
+          animateGradient={focusedId === 'readme-continue'}
+          onPress={onContinue}
+        />
+      </Box>
+
+      <Box>
+        <Text dimColor>↑ ↓ navigate · ← → switch option · Enter select · Esc Esc exit</Text>
+      </Box>
+    </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 43dba265..0acee9ad 100644
--- a/packages/cli/src/tui/views/edit/use-edit-session.ts
+++ b/packages/cli/src/tui/views/edit/use-edit-session.ts
@@ -1,11 +1,16 @@
 import {
   addSkillCompanion,
   addTopLevelFile,
+  applyReadmeDeclaration,
   type EditContext,
   type EditOperation,
   type EditResult,
+  type ReadmeAction,
+  type ReadmePath,
+  type ReadmeResolution,
   type ReconciliationItem,
   type ReconciliationResolution,
+  readmeFileOperations,
   reconciliationItemKey,
   removeSkillCompanion,
   removeTopLevelFile,
@@ -102,15 +107,34 @@ function applySupplementaryDeltas(manifest: FacetManifest, resolved: ResolvedIte
   return next
 }
 
+/**
+ * Apply queued README declaration deltas to the manifest. README file bytes
+ * travel as separate `write-file`/`delete-file` operations (see
+ * `buildOperations`); only the top-level `files` declaration is mutated here.
+ */
+function applyReadmeDeltas(manifest: FacetManifest, readme: ReadmeResolution[]): FacetManifest {
+  let next = manifest
+  for (const resolution of readme) {
+    next = applyReadmeDeclaration(next, resolution)
+  }
+  return next
+}
+
 /** Builds the queued operation list from resolutions + form asset changes. */
 function buildOperations(
   context: EditContext,
   form: FormState,
   resolved: ResolvedItem[],
+  readme: ReadmeResolution[],
   finalManifest: FacetManifest,
 ): EditOperation[] {
   const operations: EditOperation[] = [{ op: 'write-manifest', manifest: finalManifest }]
 
+  // README file writes/deletes queued from the dedicated panel.
+  for (const resolution of readme) {
+    operations.push(...readmeFileOperations(resolution))
+  }
+
   // Supplementary + asset scaffolds driven by reconciliation resolutions.
   for (const { item, resolution } of resolved) {
     if (item.kind === 'asset-missing' && resolution.action === 'scaffold') {
@@ -160,8 +184,15 @@ function buildOperations(
   return operations
 }
 
-export function useEditSession(context: EditContext, initialResolutions?: Map<string, ResolvedItem>) {
+export function useEditSession(
+  context: EditContext,
+  initialResolutions?: Map<string, ResolvedItem>,
+  initialReadme?: Map<ReadmePath, ReadmeAction>,
+) {
   const [resolutions, setResolutions] = useState<Map<string, ResolvedItem>>(() => new Map(initialResolutions))
+  // README actions are keyed by their exact conventional path; each of the two
+  // paths is managed independently (design D11), never merged into one choice.
+  const [readmeActions, setReadmeActions] = useState<Map<ReadmePath, ReadmeAction>>(() => new Map(initialReadme))
 
   const resolve = useCallback((item: ReconciliationItem, resolution: ReconciliationResolution) => {
     setResolutions((prev) => {
@@ -171,15 +202,28 @@ export function useEditSession(context: EditContext, initialResolutions?: Map<st
     })
   }, [])
 
+  const resolveReadme = useCallback((path: ReadmePath, action: ReadmeAction) => {
+    setReadmeActions((prev) => {
+      const next = new Map(prev)
+      next.set(path, action)
+      return next
+    })
+  }, [])
+
   const buildResult = useCallback(
     (form: FormState): EditResult => {
       const resolved = Array.from(resolutions.values())
-      const finalManifest = applySupplementaryDeltas(buildManifest(context.manifest, form), resolved)
-      const operations = buildOperations(context, form, resolved, finalManifest)
+      // Only non-`none` README actions produce declaration/file changes.
+      const readme: ReadmeResolution[] = Array.from(readmeActions.entries())
+        .filter(([, action]) => action.kind !== 'none')
+        .map(([path, action]) => ({ path, action }))
+      const withSupplementary = applySupplementaryDeltas(buildManifest(context.manifest, form), resolved)
+      const finalManifest = applyReadmeDeltas(withSupplementary, readme)
+      const operations = buildOperations(context, form, resolved, readme, finalManifest)
       return { outcome: 'applied', operations }
     },
-    [context, resolutions],
+    [context, resolutions, readmeActions],
   )
 
-  return { resolutions, resolve, buildResult }
+  return { resolutions, resolve, readmeActions, resolveReadme, buildResult }
 }
diff --git a/packages/cli/src/tui/views/edit/wizard.tsx b/packages/cli/src/tui/views/edit/wizard.tsx
index e1bed740..0816b082 100644
--- a/packages/cli/src/tui/views/edit/wizard.tsx
+++ b/packages/cli/src/tui/views/edit/wizard.tsx
@@ -1,4 +1,12 @@
-import type { EditContext, EditOperation, EditResult } from '@agent-facets/engine'
+import type {
+  EditContext,
+  EditOperation,
+  EditResult,
+  ReadmeAction,
+  ReadmeActionOption,
+  ReadmePath,
+} from '@agent-facets/engine'
+import { readmeActionFor, readmeSeedContent } from '@agent-facets/engine'
 import { useApp } from 'ink'
 import { useCallback, useEffect, useMemo, useState } from 'react'
 import { FocusModeProvider, useFocusMode } from '../../context/focus-mode-context.ts'
@@ -10,17 +18,30 @@ import { useNavigationKeys } from '../../hooks/use-navigation-keys.ts'
 import { EditConfirmView } from './edit-confirm-view.tsx'
 import { EditView } from './edit-view.tsx'
 import { manifestToFormState } from './manifest-to-form.ts'
+import { ReadmePanelView } from './readme-panel-view.tsx'
 import { ReconciliationView } from './reconciliation-view.tsx'
 import { EditSuccessView } from './success-view.tsx'
 import { type ResolvedItem, useEditSession } from './use-edit-session.ts'
 
-type EditPhase = 'reconciliation' | 'editing' | 'confirmation' | 'done'
+type EditPhase = 'reconciliation' | 'readme' | 'editing' | 'confirmation' | 'done'
+
+/**
+ * An external-editor round-trip request. Tagged so an asset-description edit and
+ * a README-body edit cannot be confused: each arm carries exactly the content
+ * handed to the editor, and the README arm carries the exact path and chosen
+ * option so the returned bytes become the right tagged action on that path.
+ */
+export type EditEditorRequest =
+  | { kind: 'asset-description'; section: AssetSectionKey; name: string; content: string }
+  | { kind: 'readme'; path: ReadmePath; option: ReadmeActionOption; content: string }
 
 export interface EditWizardSnapshot {
   phase: EditPhase
   formState?: FormState
   focusedId?: string | null
   resolutions: Map<string, ResolvedItem>
+  /** Queued README actions per conventional path; survives editor round-trips. */
+  readmeActions: Map<ReadmePath, ReadmeAction>
   selectedItem?: {
     section: AssetSectionKey
     name: string
@@ -37,7 +58,7 @@ export interface EditWizardProps {
   /** Argument suffix for the "facet build" hint (e.g. " my-dir" or ""). */
   buildArg?: string
   onSnapshot?: (snapshot: EditWizardSnapshot) => void
-  onRequestEditor?: (section: AssetSectionKey, name: string, description: string) => void
+  onRequestEditor?: (request: EditEditorRequest) => void
 }
 
 function EditWizardInner({
@@ -55,19 +76,23 @@ function EditWizardInner({
   const { focusedId, focus } = useFocusOrder()
   const hasReconciliation = context.reconciliationItems.length > 0
 
-  const initialPhase = snapshot?.phase ?? (hasReconciliation ? 'reconciliation' : 'editing')
+  const initialPhase = snapshot?.phase ?? (hasReconciliation ? 'reconciliation' : 'readme')
   const [phase, setPhase] = useState<EditPhase>(initialPhase)
   const [doneOperations, setDoneOperations] = useState<EditOperation[]>([])
-  // 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)
+  // Seed from the snapshot so resolutions and README actions survive
+  // external-editor round-trips (which unmount and remount the wizard).
+  const { resolutions, resolve, readmeActions, resolveReadme, buildResult } = useEditSession(
+    context,
+    snapshot?.resolutions,
+    snapshot?.readmeActions,
+  )
 
   // Report snapshot to parent for editor round-trips
   useEffect(() => {
     if (phase !== 'done') {
-      onSnapshot?.({ phase, formState: form, focusedId, resolutions })
+      onSnapshot?.({ phase, formState: form, focusedId, resolutions, readmeActions })
     }
-  }, [phase, form, focusedId, resolutions, onSnapshot])
+  }, [phase, form, focusedId, resolutions, readmeActions, onSnapshot])
 
   // Defer exit so React paints the success view before Ink unmounts.
   useEffect(() => {
@@ -87,11 +112,33 @@ function EditWizardInner({
   const handleEditDescription = useCallback(
     (section: AssetSectionKey, name: string) => {
       const description = form.assets[section].descriptions[name] ?? ''
-      onRequestEditor?.(section, name, description)
+      onRequestEditor?.({ kind: 'asset-description', section, name, content: description })
     },
     [form, onRequestEditor],
   )
 
+  // Non-content README choices queue immediately; content choices route to the
+  // external editor and are applied when the round-trip returns (see command
+  // runner). `scaffold` writes bytes without an editor, so it is seeded from the
+  // facet identity template here; declaration-only actions ignore the content.
+  const handleReadmeResolve = useCallback(
+    (path: ReadmePath, option: ReadmeActionOption) => {
+      const state = context.readme.find((s) => s.path === path)
+      const seed = state ? readmeSeedContent(state, form.fields.name.value, form.fields.description.value) : ''
+      resolveReadme(path, readmeActionFor(option.kind, seed))
+    },
+    [context.readme, form.fields.name.value, form.fields.description.value, resolveReadme],
+  )
+
+  const handleReadmeEdit = useCallback(
+    (path: ReadmePath, option: ReadmeActionOption) => {
+      const state = context.readme.find((s) => s.path === path)
+      const seed = state?.state === 'present-declared' || state?.state === 'present-undeclared' ? state.content : ''
+      onRequestEditor?.({ kind: 'readme', path, option, content: seed })
+    },
+    [context.readme, onRequestEditor],
+  )
+
   const handleConfirm = useCallback(async () => {
     const result = buildResult(form)
     onComplete(result)
@@ -114,6 +161,18 @@ function EditWizardInner({
         items={context.reconciliationItems}
         resolutions={resolutions}
         onResolve={resolve}
+        onContinue={() => setPhase('readme')}
+      />
+    )
+  }
+
+  if (phase === 'readme') {
+    return (
+      <ReadmePanelView
+        states={context.readme}
+        actions={readmeActions}
+        onResolve={handleReadmeResolve}
+        onEditReadme={handleReadmeEdit}
         onContinue={() => setPhase('editing')}
       />
     )
diff --git a/packages/engine/src/__tests__/edit-supplementary.test.ts b/packages/engine/src/__tests__/edit-supplementary.test.ts
index 5cd37fb2..7b951927 100644
--- a/packages/engine/src/__tests__/edit-supplementary.test.ts
+++ b/packages/engine/src/__tests__/edit-supplementary.test.ts
@@ -8,6 +8,14 @@ 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 {
+  applyReadmeDeclaration,
+  README_CREATE_DEFAULT,
+  readmeActionFor,
+  readmeActionOptions,
+  readmeFileOperations,
+  readmeOptionKindFor,
+} from '../edit/readme-actions.ts'
 import { computeReadmeStates } from '../edit/readme-state.ts'
 import { reconcileSupplementary } from '../edit/reconcile-supplementary.ts'
 import { scanCommonRootFiles, scanSkillCompanions } from '../edit/scanner.ts'
@@ -108,6 +116,93 @@ describe('computeReadmeStates', () => {
   })
 })
 
+// --- README actions ---
+
+describe('readmeActionOptions', () => {
+  test('present-declared offers Edit and Remove', () => {
+    const opts = readmeActionOptions({ path: 'README.md', state: 'present-declared', content: '# x' })
+    expect(opts.map((o) => o.kind)).toEqual(['edit', 'remove'])
+    expect(opts.find((o) => o.kind === 'edit')?.requiresEditor).toBe(true)
+    expect(opts.find((o) => o.kind === 'remove')?.requiresEditor).toBe(false)
+  })
+
+  test('present-undeclared offers Adopt and Edit-and-adopt', () => {
+    const opts = readmeActionOptions({ path: 'README.md', state: 'present-undeclared', content: '# x' })
+    expect(opts.map((o) => o.kind)).toEqual(['adopt', 'edit-and-adopt'])
+    expect(opts.find((o) => o.kind === 'adopt')?.requiresEditor).toBe(false)
+  })
+
+  test('declared-missing offers Scaffold and Remove Declaration', () => {
+    const opts = readmeActionOptions({ path: 'README', state: 'declared-missing' })
+    expect(opts.map((o) => o.kind)).toEqual(['scaffold', 'remove-declaration'])
+    expect(opts.find((o) => o.kind === 'scaffold')?.label).toContain('README')
+  })
+
+  test('absent-undeclared offers only Create', () => {
+    const opts = readmeActionOptions({ path: 'README', state: 'absent-undeclared' })
+    expect(opts.map((o) => o.kind)).toEqual(['create'])
+    expect(README_CREATE_DEFAULT).toBe('README.md')
+  })
+})
+
+describe('readme action derivation', () => {
+  test('adopt adds declaration and writes no file (preserves bytes)', () => {
+    const action = readmeActionFor('adopt', '# ignored')
+    const ops = readmeFileOperations({ path: 'README.md', action })
+    expect(ops).toEqual([])
+    const m = applyReadmeDeclaration({ name: 't', version: '1.0.0' }, { path: 'README.md', action })
+    expect(m.files).toEqual(['README.md'])
+  })
+
+  test('edit-and-adopt writes bytes and adds declaration', () => {
+    const action = readmeActionFor('edit-and-adopt', '# edited')
+    const ops = readmeFileOperations({ path: 'README.md', action })
+    expect(ops).toEqual([{ op: 'write-file', path: 'README.md', content: '# edited' }])
+    const m = applyReadmeDeclaration({ name: 't', version: '1.0.0' }, { path: 'README.md', action })
+    expect(m.files).toEqual(['README.md'])
+  })
+
+  test('remove deletes file and drops declaration together', () => {
+    const action = readmeActionFor('remove', '')
+    const ops = readmeFileOperations({ path: 'README.md', action })
+    expect(ops).toEqual([{ op: 'delete-file', path: 'README.md' }])
+    const m = applyReadmeDeclaration(
+      { name: 't', version: '1.0.0', files: ['README.md'] },
+      { path: 'README.md', action },
+    )
+    expect('files' in m).toBe(false)
+  })
+
+  test('scaffold at exact declared path writes bytes; declaration already present stays', () => {
+    const action = readmeActionFor('scaffold', '# t\n')
+    const ops = readmeFileOperations({ path: 'README', action })
+    expect(ops).toEqual([{ op: 'write-file', path: 'README', content: '# t\n' }])
+    const m = applyReadmeDeclaration({ name: 't', version: '1.0.0', files: ['README'] }, { path: 'README', action })
+    expect(m.files).toEqual(['README'])
+  })
+
+  test('remove-declaration drops declaration and writes no file', () => {
+    const action = readmeActionFor('remove-declaration', '')
+    const ops = readmeFileOperations({ path: 'README', action })
+    expect(ops).toEqual([])
+    const m = applyReadmeDeclaration({ name: 't', version: '1.0.0', files: ['README'] }, { path: 'README', action })
+    expect('files' in m).toBe(false)
+  })
+
+  test('create defaults to README.md, writes bytes and declares', () => {
+    const action = readmeActionFor('create', '# new\n')
+    const ops = readmeFileOperations({ path: README_CREATE_DEFAULT, action })
+    expect(ops).toEqual([{ op: 'write-file', path: 'README.md', content: '# new\n' }])
+    const m = applyReadmeDeclaration({ name: 't', version: '1.0.0' }, { path: README_CREATE_DEFAULT, action })
+    expect(m.files).toEqual(['README.md'])
+  })
+
+  test('readmeOptionKindFor round-trips a chosen option', () => {
+    expect(readmeOptionKindFor(readmeActionFor('edit', 'x'))).toBe('edit')
+    expect(readmeOptionKindFor({ kind: 'none' })).toBeNull()
+  })
+})
+
 // --- Declaration mutations ---
 
 describe('declaration mutations', () => {
diff --git a/packages/engine/src/edit/readme-actions.ts b/packages/engine/src/edit/readme-actions.ts
new file mode 100644
index 00000000..6662b29e
--- /dev/null
+++ b/packages/engine/src/edit/readme-actions.ts
@@ -0,0 +1,177 @@
+import type { FacetManifest } from '@agent-facets/protocol'
+import { README_MD, type ReadmePath, readmeTemplate } from '../readme.ts'
+import { addTopLevelFile, removeTopLevelFile } from './declarations.ts'
+import type { EditOperation, ReadmeFileState } from './types.ts'
+
+/**
+ * The action queued for one conventional README path, tagged so that each
+ * variant is only ever constructed for a state that permits it (see
+ * `readmeActionOptions`). Byte-preservation on adoption is structural: `adopt`
+ * carries no content and therefore queues no file write, while every content
+ * mutation (`edit`, `edit-and-adopt`, `create`, `scaffold`) carries the exact
+ * bytes to write. There is no representable "adopt but also rewrite bytes"
+ * combination.
+ *
+ * - `none`             — leave the path untouched (the default for every state).
+ * - `edit`             — present & declared: rewrite bytes; declaration stays.
+ * - `remove`           — present & declared: delete the file and its declaration.
+ * - `adopt`            — present & undeclared: add the declaration only.
+ * - `edit-and-adopt`   — present & undeclared: rewrite bytes and add declaration.
+ * - `scaffold`         — declared & missing: write bytes at the exact declared path.
+ * - `remove-declaration` — declared & missing: drop the declaration only.
+ * - `create`           — absent & undeclared: write bytes and add the declaration.
+ */
+export type ReadmeAction =
+  | { kind: 'none' }
+  | { kind: 'edit'; content: string }
+  | { kind: 'remove' }
+  | { kind: 'adopt' }
+  | { kind: 'edit-and-adopt'; content: string }
+  | { kind: 'scaffold'; content: string }
+  | { kind: 'remove-declaration' }
+  | { kind: 'create'; content: string }
+
+/** A README path paired with the action the author queued for it. */
+export interface ReadmeResolution {
+  path: ReadmePath
+  action: ReadmeAction
+}
+
+/**
+ * One selectable option in the README panel: a stable action `kind` (used to
+ * reconstruct the tagged action and as a focus/lookup key) plus its label. The
+ * two content-bearing option kinds are marked `requiresEditor` so the panel
+ * knows to open the external editor before finalizing the action. Options are
+ * legal-only per state — the panel never offers an action a state forbids.
+ */
+export interface ReadmeActionOption {
+  /** The action variant this option produces. `none` is never listed. */
+  kind: Exclude<ReadmeAction['kind'], 'none'>
+  label: string
+  /** True when choosing this option must gather content from the editor first. */
+  requiresEditor: boolean
+}
+
+/**
+ * The legal panel options for a README state, in display order. This is the
+ * single source of truth for which actions each state permits; the panel
+ * renders these and `readmeActionFor` maps a chosen option back to a tagged
+ * action, so an illegal state/action pairing is never constructed.
+ */
+export function readmeActionOptions(state: ReadmeFileState): ReadmeActionOption[] {
+  switch (state.state) {
+    case 'present-declared':
+      return [
+        { kind: 'edit', label: 'Edit', requiresEditor: true },
+        { kind: 'remove', label: 'Remove', requiresEditor: false },
+      ]
+    case 'present-undeclared':
+      return [
+        { kind: 'adopt', label: 'Adopt', requiresEditor: false },
+        { kind: 'edit-and-adopt', label: 'Edit and adopt', requiresEditor: true },
+      ]
+    case 'declared-missing':
+      return [
+        { kind: 'scaffold', label: `Scaffold at ${state.path}`, requiresEditor: false },
+        { kind: 'remove-declaration', label: 'Remove declaration', requiresEditor: false },
+      ]
+    case 'absent-undeclared':
+      return [{ kind: 'create', label: 'Create', requiresEditor: true }]
+  }
+}
+
+/**
+ * Build the tagged action for a chosen option kind. `content` is required for
+ * the content-bearing kinds and ignored otherwise; callers pass the
+ * editor-produced bytes for editor options and the seed template for
+ * non-editor content options. Returns `none` for any kind not legal here,
+ * which never happens for options produced by `readmeActionOptions`.
+ */
+export function readmeActionFor(kind: ReadmeActionOption['kind'], content: string): ReadmeAction {
+  switch (kind) {
+    case 'edit':
+      return { kind: 'edit', content }
+    case 'remove':
+      return { kind: 'remove' }
+    case 'adopt':
+      return { kind: 'adopt' }
+    case 'edit-and-adopt':
+      return { kind: 'edit-and-adopt', content }
+    case 'scaffold':
+      return { kind: 'scaffold', content }
+    case 'remove-declaration':
+      return { kind: 'remove-declaration' }
+    case 'create':
+      return { kind: 'create', content }
+  }
+}
+
+/** The option kind a stored action corresponds to, or null for `none`. */
+export function readmeOptionKindFor(action: ReadmeAction): ReadmeActionOption['kind'] | null {
+  return action.kind === 'none' ? null : action.kind
+}
+
+/**
+ * Apply a README path's declaration delta to the manifest. Content is never
+ * touched here — file bytes travel as `write-file`/`delete-file` operations
+ * (see `readmeFileOperations`). Adopt/edit-and-adopt/scaffold/create add the
+ * declaration (idempotent); remove/remove-declaration drop it; edit/none leave
+ * it as-is.
+ */
+export function applyReadmeDeclaration(manifest: FacetManifest, resolution: ReadmeResolution): FacetManifest {
+  const { path, action } = resolution
+  switch (action.kind) {
+    case 'adopt':
+    case 'edit-and-adopt':
+    case 'create':
+    case 'scaffold':
+      return addTopLevelFile(manifest, path)
+    case 'remove':
+    case 'remove-declaration':
+      return removeTopLevelFile(manifest, path)
+    case 'edit':
+    case 'none':
+      return manifest
+  }
+}
+
+/**
+ * The exact-path file operations a README action queues. Content mutations emit
+ * `write-file` at the exact path; removal emits `delete-file`. Adopt and
+ * remove-declaration touch only the manifest and so emit no file operation —
+ * adoption preserving on-disk bytes falls out of this structurally.
+ */
+export function readmeFileOperations(resolution: ReadmeResolution): EditOperation[] {
+  const { path, action } = resolution
+  switch (action.kind) {
+    case 'edit':
+    case 'edit-and-adopt':
+    case 'scaffold':
+    case 'create':
+      return [{ op: 'write-file', path, content: action.content }]
+    case 'remove':
+      return [{ op: 'delete-file', path }]
+    case 'adopt':
+    case 'remove-declaration':
+    case 'none':
+      return []
+  }
+}
+
+/** The seed content offered when an author opens the editor for a README path. */
+export function readmeSeedContent(state: ReadmeFileState, name: string, description: string): string {
+  switch (state.state) {
+    case 'present-declared':
+    case 'present-undeclared':
+      // Existing bytes are the editor seed; the author edits from what is there.
+      return state.content
+    case 'declared-missing':
+    case 'absent-undeclared':
+      // No bytes on disk — seed from the facet identity, sharing the same
+      // template create uses so there is one source of README seed content.
+      return readmeTemplate(name, description)
+  }
+}
+
+/** The default README path for Create (design D11: `README.md`). */
+export const README_CREATE_DEFAULT: ReadmePath = README_MD
diff --git a/packages/engine/src/index.ts b/packages/engine/src/index.ts
index ffe64bb5..e2234729 100644
--- a/packages/engine/src/index.ts
+++ b/packages/engine/src/index.ts
@@ -107,6 +107,16 @@ 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 { ReadmeAction, ReadmeActionOption, ReadmeResolution } from './edit/readme-actions.ts'
+export {
+  applyReadmeDeclaration,
+  README_CREATE_DEFAULT,
+  readmeActionFor,
+  readmeActionOptions,
+  readmeFileOperations,
+  readmeOptionKindFor,
+  readmeSeedContent,
+} from './edit/readme-actions.ts'
 export type { MatchedAsset, MissingAsset, ReconciliationResult } from './edit/reconcile.ts'
 export { reconcile } from './edit/reconcile.ts'
 export {

From 9ba621d0e5773f365ef71ab9f7870c7ca87552b1 Mon Sep 17 00:00:00 2001
From: Julian Coy <julian@ex-machina.co>
Date: Thu, 23 Jul 2026 21:09:39 -0400
Subject: [PATCH 2/2] TODO

---
 .../changes/support-non-asset-files/tasks.md  |   4 +-
 .../src/__tests__/create-build.e2e.test.ts    |  50 +++++++
 .../views/__tests__/confirm-privacy.test.tsx  |  33 +++++
 .../edit/__tests__/readme-session.test.tsx    | 135 ++++++++++++++++++
 .../src/__tests__/edit-supplementary.test.ts  |  79 ++++++++++
 5 files changed, 299 insertions(+), 2 deletions(-)
 create mode 100644 packages/cli/src/tui/views/edit/__tests__/readme-session.test.tsx

diff --git a/openspec/changes/support-non-asset-files/tasks.md b/openspec/changes/support-non-asset-files/tasks.md
index ef87b2cc..d4f9e133 100644
--- a/openspec/changes/support-non-asset-files/tasks.md
+++ b/openspec/changes/support-non-asset-files/tasks.md
@@ -129,8 +129,8 @@
 - [x] 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
 - [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
+- [x] 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
+- [x] 13.8 Verify: Run focused scaffold, edit, create, TUI, integration, and end-to-end tests
 
 ## 14. Documentation — Research
 
diff --git a/packages/cli/src/__tests__/create-build.e2e.test.ts b/packages/cli/src/__tests__/create-build.e2e.test.ts
index 812e4e08..951b7713 100644
--- a/packages/cli/src/__tests__/create-build.e2e.test.ts
+++ b/packages/cli/src/__tests__/create-build.e2e.test.ts
@@ -222,6 +222,34 @@ describe('writeScaffold', () => {
     const looseManifest = await Bun.file(join(dir, 'dist/facet.json')).exists()
     expect(looseManifest).toBe(false)
   })
+
+  test('scaffolded project with an enabled README builds successfully', async () => {
+    const dir = await createFixtureDir('scaffold-readme-buildable')
+    const files = await writeScaffold(
+      {
+        name: 'readme-facet',
+        version: DEFAULT_VERSION,
+        description: 'Has a README',
+        skills: ['helper'],
+        agents: [],
+        commands: [],
+        readme: { kind: 'enabled', content: '# readme-facet\n\nHas a README\n' },
+      },
+      dir,
+    )
+    // README is written and declared as a top-level supplementary file.
+    expect(files).toContain('README.md')
+    const manifest = JSON.parse(await Bun.file(join(dir, 'facet.json')).text())
+    expect(manifest.files).toEqual(['README.md'])
+    expect(await Bun.file(join(dir, 'README.md')).text()).toBe('# readme-facet\n\nHas a README\n')
+
+    // The README-bearing project builds without error into a self-contained archive.
+    const result = await runCli('build', dir)
+    expect(result.exitCode).toBe(0)
+    expect(result.stdout).toContain('Built readme-facet')
+    const distArchive = await Bun.file(join(dir, `dist/readme-facet-${DEFAULT_VERSION}.facet`)).exists()
+    expect(distArchive).toBe(true)
+  })
 })
 
 // --- Headless create (e2e) ---
@@ -254,6 +282,28 @@ describe('facet create — headless', () => {
     expect(manifest.agents.helper).toBeDefined()
   })
 
+  test('writes a default README.md and declares it', async () => {
+    const dir = await createFixtureDir('create-headless-readme')
+    const result = await runCli('create', dir, '--name', 'doc-facet', '--description', 'Docs', '--skill', 'greet')
+    expect(result.exitCode).toBe(0)
+
+    // Default-on README is written and declared, matching the interactive default.
+    expect(await Bun.file(join(dir, 'README.md')).exists()).toBe(true)
+    expect(await Bun.file(join(dir, 'README.md')).text()).toBe('# doc-facet\n\nDocs\n')
+    const manifest = JSON.parse(await Bun.file(join(dir, 'facet.json')).text())
+    expect(manifest.files).toEqual(['README.md'])
+  })
+
+  test('--no-readme omits the README file and declaration', async () => {
+    const dir = await createFixtureDir('create-headless-noreadme')
+    const result = await runCli('create', dir, '--name', 'bare-facet', '--skill', 'greet', '--no-readme')
+    expect(result.exitCode).toBe(0)
+
+    expect(await Bun.file(join(dir, 'README.md')).exists()).toBe(false)
+    const manifest = JSON.parse(await Bun.file(join(dir, 'facet.json')).text())
+    expect('files' in manifest).toBe(false)
+  })
+
   test('missing --name fails with a clear error', async () => {
     const dir = await createFixtureDir('create-headless-noname')
     const result = await runCli('create', dir, '--skill', 'greet')
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 deda3cab..fe0d3ac4 100644
--- a/packages/cli/src/tui/views/__tests__/confirm-privacy.test.tsx
+++ b/packages/cli/src/tui/views/__tests__/confirm-privacy.test.tsx
@@ -1,4 +1,5 @@
 import { describe, expect, test } from 'bun:test'
+import type { EditOperation } from '@agent-facets/engine'
 import { render } from 'ink-testing-library'
 import { FocusOrderProvider } from '../../context/focus-order-context.ts'
 import { type FormState, FormStateProvider } from '../../context/form-state-context.ts'
@@ -86,3 +87,35 @@ describe('edit confirmation summary privacy', () => {
     instance.unmount()
   })
 })
+
+describe('edit confirmation lists queued README operations', () => {
+  function renderEditWithOps(operations: EditOperation[]) {
+    return render(
+      <FocusOrderProvider>
+        <FormStateProvider initialState={formWith(false)}>
+          <EditConfirmView operations={operations} onConfirm={() => {}} onBack={() => {}} />
+        </FormStateProvider>
+      </FocusOrderProvider>,
+    )
+  }
+
+  test('shows the exact README path and verb for a queued write', () => {
+    const instance = renderEditWithOps([
+      { op: 'write-manifest', manifest: { name: 'cowsay', version: '0.0.0', files: ['README.md'] } },
+      { op: 'write-file', path: 'README.md', content: '# cowsay\n' },
+    ])
+    const frame = instance.lastFrame() ?? ''
+    expect(frame).toContain('File changes:')
+    expect(frame).toContain('Write README.md')
+    instance.unmount()
+  })
+
+  test('shows a queued README removal as a delete of the exact path', () => {
+    const instance = renderEditWithOps([
+      { op: 'write-manifest', manifest: { name: 'cowsay', version: '0.0.0' } },
+      { op: 'delete-file', path: 'README' },
+    ])
+    expect(instance.lastFrame() ?? '').toContain('Delete README')
+    instance.unmount()
+  })
+})
diff --git a/packages/cli/src/tui/views/edit/__tests__/readme-session.test.tsx b/packages/cli/src/tui/views/edit/__tests__/readme-session.test.tsx
new file mode 100644
index 00000000..8a234c1d
--- /dev/null
+++ b/packages/cli/src/tui/views/edit/__tests__/readme-session.test.tsx
@@ -0,0 +1,135 @@
+import { describe, expect, test } from 'bun:test'
+import {
+  type EditContext,
+  type EditOperation,
+  type EditResult,
+  type ReadmeAction,
+  type ReadmeFileState,
+  type ReadmePath,
+  readmeActionFor,
+} from '@agent-facets/engine'
+import type { FacetManifest } from '@agent-facets/protocol'
+import { render } from 'ink-testing-library'
+import { useEffect } from 'react'
+import { manifestToFormState } from '../manifest-to-form.ts'
+import { useEditSession } from '../use-edit-session.ts'
+
+/**
+ * Drives README resolutions on mount, then reports the operations `buildResult`
+ * produces so assertions observe the settled edit output. README bytes and
+ * declarations are derived purely from the queued actions — this exercises the
+ * `use-edit-session` wiring that the dedicated README panel drives.
+ */
+function Probe({
+  context,
+  steps,
+  report,
+}: {
+  context: EditContext
+  steps: (resolveReadme: (path: ReadmePath, action: ReadmeAction) => void) => void
+  report: (r: EditResult) => void
+}) {
+  const { resolveReadme, buildResult } = useEditSession(context)
+  useEffect(() => {
+    steps(resolveReadme)
+  }, [steps, resolveReadme])
+  report(buildResult(manifestToFormState(context.manifest)))
+  return null
+}
+
+function nextTick(): Promise<void> {
+  return new Promise((resolve) => setImmediate(resolve))
+}
+
+async function run(
+  context: EditContext,
+  steps: (resolveReadme: (path: ReadmePath, action: ReadmeAction) => void) => void,
+): Promise<EditOperation[]> {
+  let result: EditResult = { outcome: 'cancelled' } as EditResult
+  const instance = render(<Probe context={context} steps={steps} report={(r) => (result = r)} />)
+  await nextTick()
+  instance.unmount()
+  if (result.outcome !== 'applied') expect.unreachable()
+  return result.operations
+}
+
+/** Build an EditContext with the given manifest and README panel states. */
+function contextWith(manifest: FacetManifest, readme: ReadmeFileState[]): EditContext {
+  return { rootDir: '/tmp/facet', manifest, reconciliationItems: [], readme }
+}
+
+/** The manifest inside the queued `write-manifest` operation. */
+function finalManifest(operations: EditOperation[]): FacetManifest {
+  const op = operations.find((o) => o.op === 'write-manifest')
+  if (op?.op !== 'write-manifest') expect.unreachable()
+  return op.manifest
+}
+
+const BASE: FacetManifest = { name: 'demo', version: '1.0.0' }
+
+describe('edit README session wiring', () => {
+  test('adopt adds the declaration and writes no README file (preserves bytes)', async () => {
+    const ctx = contextWith(BASE, [{ path: 'README.md', state: 'present-undeclared', content: '# on disk' }])
+    const ops = await run(ctx, (resolveReadme) => {
+      resolveReadme('README.md', readmeActionFor('adopt', ''))
+    })
+    // No file op — on-disk bytes are untouched.
+    expect(ops.some((o) => o.op === 'write-file' || o.op === 'delete-file')).toBe(false)
+    expect(finalManifest(ops).files).toEqual(['README.md'])
+  })
+
+  test('create queues a write-file and adds the declaration', async () => {
+    const ctx = contextWith(BASE, [{ path: 'README.md', state: 'absent-undeclared' }])
+    const ops = await run(ctx, (resolveReadme) => {
+      resolveReadme('README.md', readmeActionFor('create', '# new\n'))
+    })
+    expect(ops).toContainEqual({ op: 'write-file', path: 'README.md', content: '# new\n' })
+    expect(finalManifest(ops).files).toEqual(['README.md'])
+  })
+
+  test('remove queues delete-file and drops the declaration', async () => {
+    const declared: FacetManifest = { ...BASE, files: ['README.md'] }
+    const ctx = contextWith(declared, [{ path: 'README.md', state: 'present-declared', content: '# old' }])
+    const ops = await run(ctx, (resolveReadme) => {
+      resolveReadme('README.md', readmeActionFor('remove', ''))
+    })
+    expect(ops).toContainEqual({ op: 'delete-file', path: 'README.md' })
+    expect('files' in finalManifest(ops)).toBe(false)
+  })
+
+  test('scaffold at the exact declared path writes bytes; declaration stays', async () => {
+    const declared: FacetManifest = { ...BASE, files: ['README'] }
+    const ctx = contextWith(declared, [{ path: 'README', state: 'declared-missing' }])
+    const ops = await run(ctx, (resolveReadme) => {
+      resolveReadme('README', readmeActionFor('scaffold', '# t\n'))
+    })
+    expect(ops).toContainEqual({ op: 'write-file', path: 'README', content: '# t\n' })
+    expect(finalManifest(ops).files).toEqual(['README'])
+  })
+
+  test('the two conventional paths are managed independently', async () => {
+    // README.md present+undeclared → adopt; README absent → create.
+    const ctx = contextWith(BASE, [
+      { path: 'README.md', state: 'present-undeclared', content: '# md' },
+      { path: 'README', state: 'absent-undeclared' },
+    ])
+    const ops = await run(ctx, (resolveReadme) => {
+      resolveReadme('README.md', readmeActionFor('adopt', ''))
+      resolveReadme('README', readmeActionFor('create', '# plain\n'))
+    })
+    // Only the created path writes a file; adoption writes nothing.
+    expect(ops.filter((o) => o.op === 'write-file')).toEqual([
+      { op: 'write-file', path: 'README', content: '# plain\n' },
+    ])
+    // Both paths end up declared, independently.
+    expect(finalManifest(ops).files).toEqual(['README', 'README.md'])
+  })
+
+  test('a path left as-is (no action) queues no README change', async () => {
+    const ctx = contextWith(BASE, [{ path: 'README.md', state: 'present-undeclared', content: '# on disk' }])
+    const ops = await run(ctx, () => {
+      // No resolveReadme call — the author leaves README alone.
+    })
+    expect(ops).toEqual([{ op: 'write-manifest', manifest: BASE }])
+  })
+})
diff --git a/packages/engine/src/__tests__/edit-supplementary.test.ts b/packages/engine/src/__tests__/edit-supplementary.test.ts
index 7b951927..fac79f93 100644
--- a/packages/engine/src/__tests__/edit-supplementary.test.ts
+++ b/packages/engine/src/__tests__/edit-supplementary.test.ts
@@ -15,6 +15,7 @@ import {
   readmeActionOptions,
   readmeFileOperations,
   readmeOptionKindFor,
+  readmeSeedContent,
 } from '../edit/readme-actions.ts'
 import { computeReadmeStates } from '../edit/readme-state.ts'
 import { reconcileSupplementary } from '../edit/reconcile-supplementary.ts'
@@ -114,6 +115,16 @@ describe('computeReadmeStates', () => {
     expect(states.find((s) => s.path === 'README.md')?.state).toBe('present-undeclared')
     expect(states.find((s) => s.path === 'README')?.state).toBe('declared-missing')
   })
+
+  test('both paths present on disk are surfaced independently, neither ignored', () => {
+    // README.md declared, extensionless README present but undeclared.
+    const manifest: FacetManifest = { name: 't', version: '1.0.0', files: ['README.md'] }
+    const states = computeReadmeStates(manifest, { present: { 'README.md': '# md', README: '# plain' } })
+    const md = states.find((s) => s.path === 'README.md')
+    const plain = states.find((s) => s.path === 'README')
+    expect(md).toEqual({ path: 'README.md', state: 'present-declared', content: '# md' })
+    expect(plain).toEqual({ path: 'README', state: 'present-undeclared', content: '# plain' })
+  })
 })
 
 // --- README actions ---
@@ -197,12 +208,50 @@ describe('readme action derivation', () => {
     expect(m.files).toEqual(['README.md'])
   })
 
+  test('edit rewrites bytes and leaves the declaration untouched', () => {
+    const action = readmeActionFor('edit', '# rewritten')
+    const ops = readmeFileOperations({ path: 'README.md', action })
+    expect(ops).toEqual([{ op: 'write-file', path: 'README.md', content: '# rewritten' }])
+    // Declaration already present; edit must not add or drop it.
+    const declared = applyReadmeDeclaration(
+      { name: 't', version: '1.0.0', files: ['README.md'] },
+      { path: 'README.md', action },
+    )
+    expect(declared.files).toEqual(['README.md'])
+  })
+
+  test('none queues nothing and touches no declaration', () => {
+    const ops = readmeFileOperations({ path: 'README.md', action: { kind: 'none' } })
+    expect(ops).toEqual([])
+    const before: FacetManifest = { name: 't', version: '1.0.0', files: ['README.md'] }
+    const after = applyReadmeDeclaration(before, { path: 'README.md', action: { kind: 'none' } })
+    expect(after.files).toEqual(['README.md'])
+  })
+
   test('readmeOptionKindFor round-trips a chosen option', () => {
     expect(readmeOptionKindFor(readmeActionFor('edit', 'x'))).toBe('edit')
     expect(readmeOptionKindFor({ kind: 'none' })).toBeNull()
   })
 })
 
+describe('readmeSeedContent', () => {
+  test('present states seed from existing bytes (adoption/edit preserves)', () => {
+    expect(readmeSeedContent({ path: 'README.md', state: 'present-declared', content: '# authored' }, 'x', 'y')).toBe(
+      '# authored',
+    )
+    expect(readmeSeedContent({ path: 'README.md', state: 'present-undeclared', content: '# on disk' }, 'x', 'y')).toBe(
+      '# on disk',
+    )
+  })
+
+  test('absent/missing states seed from the identity template, not stale bytes', () => {
+    expect(readmeSeedContent({ path: 'README.md', state: 'absent-undeclared' }, 'my-facet', 'Neat tools')).toBe(
+      '# my-facet\n\nNeat tools\n',
+    )
+    expect(readmeSeedContent({ path: 'README', state: 'declared-missing' }, 'my-facet', '')).toBe('# my-facet\n')
+  })
+})
+
 // --- Declaration mutations ---
 
 describe('declaration mutations', () => {
@@ -270,6 +319,36 @@ describe('applyEditOperations', () => {
     expect(existsSync(join(dir, 'skills/review/notes.txt'))).toBe(true)
   })
 
+  test('delete-file removes a supplementary file transactionally (README remove)', async () => {
+    await writeFile('README.md', '# old')
+    const ops: EditOperation[] = [
+      { op: 'write-manifest', manifest: { name: 'test', version: '1.0.0' } },
+      { op: 'delete-file', path: 'README.md' },
+    ]
+    const result = await applyEditOperations(ops, dir)
+    expect(result.ok).toBe(true)
+    expect(existsSync(join(dir, 'README.md'))).toBe(false)
+  })
+
+  test('rolls back a delete-file when a later op fails, restoring the file and manifest', async () => {
+    await writeFile('facet.json', 'ORIGINAL')
+    await writeFile('README.md', '# keep me')
+    // `skills` is a file, so the scaffold-asset write fails after the delete.
+    await writeFile('skills', 'not a dir')
+    const ops: EditOperation[] = [
+      { op: 'write-manifest', manifest },
+      { op: 'delete-file', path: 'README.md' },
+      { 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)
+    // The deleted README is restored to its original bytes.
+    expect(readFileSync(join(dir, 'README.md'), 'utf8')).toBe('# keep me')
+    expect(readFileSync(join(dir, 'facet.json'), 'utf8')).toBe('ORIGINAL')
+  })
+
   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.