> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentfacets.io/llms.txt
> Use this file to discover all available pages before exploring further.

# facet edit

> Interactively edit a facet

## Usage

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
facet edit [directory]
```

Opens an interactive editor for the facet in the specified directory (defaults to the current directory). The edit command is the full authoring workbench  -- everything `facet create` can do, plus automatic reconciliation of disk state versus the manifest.

<Note>
  `facet edit` is interactive (TTY only). For scripted or agent-driven edits, use [`facet modify`](/cli/authoring/modify)  -- the headless, flag-driven counterpart.
</Note>

## Exit codes

| Code | Meaning                       |
| ---- | ----------------------------- |
| `0`  | Changes applied successfully  |
| `1`  | Cancelled or manifest invalid |

## What it does

The edit command has two phases:

### Reconciliation

If the edit command detects drift between the manifest and the files on disk, it enters a reconciliation phase first. Drift includes:

* **New assets on disk** not tracked in the manifest  -- choose "Add to manifest" or "Ignore for now"
* **Undeclared files inside a declared skill directory**  -- adopt them into that skill's [companion `files`](/specification/manifest#supplementary-files), or ignore
* **Common root files** like `LICENSE`  -- adopt them into the top-level `files`, or ignore
* **Missing files** declared in the manifest but absent from disk  -- choose "Scaffold template" or "Remove from manifest" (at the exact declared path, for both assets and supplementary files)

`README.md` and the extensionless `README` are handled by their own [README panel](#readme-panel), not generic reconciliation, so they never appear twice. Ignored files stay on disk and undeclared.

All reconciliation items must be resolved before proceeding to editing.

### Editing

After reconciliation (or immediately if no drift), the edit phase allows:

* **Identity editing**  -- modify the facet name, description, and version
* **Privacy editing**  -- inspect the facet's current visibility intent without opening `facet.json`, and switch between Public and Private.
* **Asset management**  -- add, remove, or rename skills, agents, and commands. Deleting a skill removes its declared companion files too, while any files you added to the skill directory yourself are preserved.
* **Description editing**  -- press Enter on an asset to edit its name, or press ↓ during name editing to open the description in your terminal editor (`$VISUAL` / `$EDITOR` / `vi`)

A primary asset file carries no YAML front matter — asset metadata lives in the manifest, and edit writes confirmed content without front matter.

All changes are transactional  -- nothing is written to disk until you review and confirm on the confirmation page. Exit at any point with Esc Esc to discard all changes.

### README panel

Both conventional README paths — `README.md` and the extensionless `README` — get a dedicated panel, managed independently. The actions offered depend on each path's current state:

| State                  | Actions                                                                    |
| ---------------------- | -------------------------------------------------------------------------- |
| Present and declared   | **Edit** the content, or **Remove** (deletes the file and its declaration) |
| Present but undeclared | **Adopt** (declare it, bytes untouched), or **Edit and adopt**             |
| Declared but missing   | **Scaffold** at that path, or **Remove declaration**                       |
| Absent and undeclared  | **Create** (defaults to `README.md`)                                       |

Adopt preserves the existing bytes unless you explicitly edit them. Every README operation is queued until Apply, like all other edits.

## Confirmation

Before applying, a summary shows the final state of your facet  -- identity fields, the privacy intent, and all assets with their descriptions  -- along with a reminder that a privacy change is embedded at build time (rebuild to apply it, and bump the version if it was already published). Choose "Apply" to write changes or "Go back" to continue editing.

The confirmation lists every queued file operation with its exact path. On apply, the edit command transactionally:

* Writes the updated `facet.json`
* Scaffolds template files for new assets
* Deletes files for removed assets (and a removed skill's declared companions)
* Writes or deletes README files per the [README panel](#readme-panel) choices
* Scaffolds or removes reconciled supplementary files

## See also

* [`facet modify`](/cli/authoring/modify) -- headless, scriptable edits.
* [`facet create`](/cli/authoring/create) -- scaffold a new facet project.