@monster-orange/den 0.4.12 → 0.4.14

package/CHANGELOG.md

@@ -4,6 +4,157 @@ All notable changes to Den are documented here. Each release lists the
 config and manifest changes a distribution must make to move to it under
 **Migrations**.
 
+## [0.4.14] - 2026-11-07
+
+### Added
+
+- **Bring in a conversation (AG-17.1).** A Claude Code conversation you
+  started in a terminal outside Den, in the workspace's folder or in one
+  of its repos' folders (a repo added by path outside it too), can become
+  a Den agent. Agents › Bring in lists them, newest first, and asks for a
+  persona; Bring in runs `claude --resume <id>` in the folder it ran in,
+  with Den's token, MCP, hooks and guards from then on. Den reads only the
+  first and last 64 KB of each transcript. A conversation written in the
+  last minute is refused: "Still open in another terminal. Close it there
+  first". CLI: `agents import -w <ws>` lists, `agents import -w <ws>
+  --session <id> --persona <p>` brings one in. MCP `agent_import` is
+  opt-in through `mcp.actions`. Routes: `GET
+  /api/workspaces/<ws>/conversations`, `POST
+  /api/workspaces/<ws>/conversations/<id>/import`. Only den-claude can
+  bring one in for now. The dialog asks you to close the
+  conversation in any other terminal first.
+- **One persona, several agents (AG-10.10).** Starting a persona that
+  already has an agent in the workspace starts another: `be-dev`, then
+  `be-dev-2`, `be-dev-3`. A stopped agent's id is never reused by a new
+  start, only by its Resume or Start fresh. The Start dialog says the id
+  it will use ("Starts as be-dev-2") and takes an optional Name. An id
+  that is running is refused, and the dialog offers "Open the running
+  one". `--id` stays exact. The start route takes `name`; `GET
+  /api/personas?workspace=<ws>` answers `startsAs`; a 409 for a running
+  agent carries `running: {id, sessionId}`.
+
+### Changed
+
+- Without `--id`, a start of a persona whose agent is stopped in that
+  workspace no longer replaces it: it starts `<persona>-2`. To continue
+  the stopped one, Resume it or Start fresh on it.
+
+### Fixed
+
+- Bring in: a long title no longer cuts off its "Agent …" badge, and each
+  "can't bring in a conversation yet" line is its own sentence.
+  Its intro names the repos' folders too.
+
+- Start › Advanced: the Model select's default reads "Persona default
+  (latest)" for a persona with no model of its own; the longer label was
+  cut off.
+- An `up` whose service exits at once with an error no longer leaves the
+  service listed. The command could exit before Den recorded its process
+  group, and then its record stayed.
+
+## [0.4.13] - 2026-11-07
+
+### Added
+
+- **The Start dialog.** + Start agent opens the dialog from the Den Shell
+  design. Pick a persona from a list you can search, with category and
+  source chips (built-in, distribution, mine); with no filter it is grouped
+  by category, and Plain session (your shell in the workspace, no agent) is
+  pinned last. Each persona shows its one-line description. "What's a
+  persona?" explains the idea, and Details shows the instructions, runtime,
+  model and version, permission mode and allowed commands. Then Runtime,
+  Workspace, an optional first instruction, and a collapsed Advanced
+  section: Model and Version, Permission mode, and Extra allowed commands,
+  with a preview of exactly what the runtime will be given.
+- **First instruction.** Den types it into the agent's session once the
+  session is ready, as a bracketed paste when the runtime asks for one,
+  then Enter. It never goes on the command line and is never stored; the
+  audit log records its length only.
+- **Your own personas.** + New persona, Duplicate and Edit write personas
+  of your own to `<state_dir>/personas/<id>.md` (0600). Settings ›
+  Personas lists every persona with the same search and chips: View or
+  Edit, Duplicate, Delete (your own only), + New persona. Built-in and
+  distribution personas are read-only; Duplicate makes your own copy.
+  Routes: `GET /api/personas/<id>`, `POST /api/personas`, `POST` and
+  `DELETE /api/personas/<id>`.
+- **Models and versions.** A runtime lists its models (den-claude: opus,
+  sonnet and haiku, each "latest" or a pinned version, from a catalog
+  shipped with Den). A pinned version runs as `--model <full id>`. A
+  persona or session pinned to an older version says "newer available";
+  your own persona has Use latest.
+- **Permissions as intent.** Ask for everything, Auto-approve edits in the
+  worktree, or Auto-approve all, plus extra allowed commands as plain
+  prefixes. den-claude turns them into `--permission-mode` and
+  `Bash(<prefix>)` / `Bash(<prefix> *)` allow rules beside Den's deny
+  rules. Other runtimes take none from Den yet, and the dialog says "not
+  supported on <runtime>" rather than dropping one.
+- **Override tags.** A session started with choices that differ from its
+  persona is tagged in the list: "model: haiku", "pinned <version>",
+  "auto-approve edits", "custom tools", the runtime. "auto-approve all" is
+  always tagged. Start fresh and Relaunch keep the choices.
+- **Roles and categories.** Den's roles are planner, orchestrator, sde,
+  reviewer, tester and designer. Each is a template (instructions,
+  permission mode, a read-only command preset) that fills in New persona
+  without overwriting what you typed, and it adds nothing hidden to a
+  prompt. A distribution adds roles and categories (`agents.roles`,
+  `agents.categories`) and may extend a Den role's preset, never redefine
+  it.
+- **Plain session from the page.** `POST /api/workspaces/<ws>/sessions`
+  starts your login shell in the workspace's folder (capped by
+  `sessions.max_concurrent`).
+- **A tester persona** in Den's default pack.
+
+
+### Changed
+
+- `POST /api/workspaces/<ws>/agents` takes `version`, `permission`,
+  `allow` and `instruction`, and refuses an unknown field. Each is checked
+  against the runtime's catalog: a model or version it doesn't list, a
+  mode other than `ask`, `edits` or `all`, or a command that isn't a plain
+  prefix (at most 32, 120 characters each) is a 400. An agent's token gets
+  403 on every persona route and on a plain session.
+- The agent record keeps `version`, `permission`, `allow` and `overrides`.
+- A persona's `role` is a role key; a sentence there still reads as its
+  description. Personas gain `display_name`, `category`, `version` and
+  `allowed_commands`. `permission_mode` takes `ask`, `edits` or `all`
+  (Claude Code's own modes still read). `agents personas` shows SOURCE and
+  ROLE columns.
+- fe-dev, be-dev and devops are role `sde`; ux-designer is role
+  `designer` in category Design.
+- A persona whose runtime isn't installed starts on the first one that is,
+  and the Start dialog says so.
+- **`sessionTitle` is the name a session shows.** `agents list --json`,
+  `GET /api/sessions` and the start and resume answers (MCP
+  `agent_resume`) now carry the resolved name (Den's rename or the
+  runtime's, the later) as `sessionTitle`. 0.4.12 called it `sessionName`,
+  which is the agent record's session handle (`<dist>-<ws>:<id>`) and has
+  been since 0.4.0. Records are unchanged.
+
+### Fixed
+
+- **Settings shows a saved choice at once.** Agents tab layout and Open
+  file links in saved, but the pressed button stayed on the old value
+  until a reload. The page now takes every setting the save returns.
+- **Claude Code's `/rename "x"` shows as x.** Its title keeps the quotes;
+  Den drops one pair around the whole name, for display only.
+- **The terminal fit check is exact again.** The browser test compares
+  what is left below and beside a terminal with the cell size xterm drew
+  with (now on each pane as `data-cell-w` and `data-cell-h`), less than
+  one cell, so a missed row fails on any font.
+
+### Migrations
+
+- None required. A persona whose `role:` is a sentence keeps working (it
+  becomes the description); set `role:` to a role key to give it one.
+- A persona pack may now set `display_name`, `category`, `version` and
+  `allowed_commands`. Use `permission_mode: ask | edits | all` for a mode
+  every runtime can translate.
+- `agents.roles` and `agents.categories` are new keys of `agents:` in the
+  distribution's config (see docs/distributions.md, Personas).
+- Read `sessionTitle`, not `sessionName`, for the name a session shows in
+  `agents list --json`, `GET /api/sessions` and the start and resume
+  answers. No record needs changing.
+
 ## [0.4.12] - 2026-11-07
 
 ### Added

package/README.md

@@ -10,8 +10,8 @@
 </p>
 
 <picture>
-  <source media="(prefers-color-scheme: dark)" srcset="docs/images/0.4.12/hero-dark.png">
-  <img src="docs/images/0.4.12/hero-light.png" width="100%" alt="Den's Graph page: the demo workspace's services grouped by application, all healthy, with the status chip and the left rail">
+  <source media="(prefers-color-scheme: dark)" srcset="docs/images/0.4.14/hero-dark.png">
+  <img src="docs/images/0.4.14/hero-light.png" width="100%" alt="Den's Graph page: the demo workspace's services grouped by application, all healthy, with the status chip and the left rail">
 </picture>
 
 ## Set up by your agent
@@ -38,7 +38,7 @@ It doesn't replace your tools. Your repos, Docker, your test runners, your secre
 yours. Den connects them and turns on good practice from the start.
 
 <p align="center">
-  <img src="docs/images/0.4.12/up.gif" width="100%" alt="make up in the Graph page: every stack down, then demo-api, demo-web and demo-notes come up in dependency order until the status chip reads All 3 healthy">
+  <img src="docs/images/0.4.14/up.gif" width="100%" alt="make up in the Graph page: every stack down, then demo-api, demo-web and demo-notes come up in dependency order until the status chip reads All 3 healthy">
 </p>
 
 ## How it helps
@@ -68,10 +68,10 @@ yours. Den connects them and turns on good practice from the start.
   lives in your own repo.
 
 <p align="center">
-  <img src="docs/images/0.4.12/agents.png" width="49%" alt="The Agents tab: the demo workspace's sessions on the left, and one open in a terminal pane on the right, running demo-api's test and then the service">
-  <img src="docs/images/0.4.12/workspaces.png" width="49%" alt="The Workspaces page: the demo workspace's repos with their health, mode and Start, Stop, Restart and Logs actions">
-  <img src="docs/images/0.4.12/status-drawer.png" width="49%" alt="The status drawer: nothing needs attention, and every service in the demo workspace, by application, with its latency">
-  <img src="docs/images/0.4.12/edge.png" width="49%" alt="The Edge page: the edge container up, its ports and TLS, and every route it serves, Den's own and each stack's, with its upstream">
+  <img src="docs/images/0.4.14/agents.png" width="49%" alt="The Agents tab: the demo workspace's sessions on the left, and one open in a terminal pane on the right, running demo-api's test and then the service">
+  <img src="docs/images/0.4.14/workspaces.png" width="49%" alt="The Workspaces page: the demo workspace's repos with their health, mode and Start, Stop, Restart and Logs actions">
+  <img src="docs/images/0.4.14/status-drawer.png" width="49%" alt="The status drawer: nothing needs attention, and every service in the demo workspace, by application, with its latency">
+  <img src="docs/images/0.4.14/edge.png" width="49%" alt="The Edge page: the edge container up, its ports and TLS, and every route it serves, Den's own and each stack's, with its upstream">
 </p>
 
 ## Get started

package/docs/distributions.md

@@ -1932,6 +1932,13 @@ orchestrator. It is off unless `mcp.actions` names it. A scoped server
 itself. The web server checks the same rule, and the resume route is the
 only agent route an agent's token reaches.
 
+`agent_import` (AG-17.1) brings in a conversation started outside Den as an
+agent: with no `session` it lists them, with `session` and `persona` it
+brings one in (see [Bring in a conversation](#bring-in-a-conversation)). It
+is off unless `mcp.actions` names it, and a scoped server reaches its own
+workspace or a granted one. Without it, an agent's token gets 403 on both
+the list and the import.
+
 ### Guards
 
 - **Lifecycle only, local only.** The service tools run a manifest's `up`,
@@ -2042,6 +2049,8 @@ server scoped to its workspace.
 <cli> agents list -w <ws> [--json]
 <cli> agents stop <id> [-w <ws>]
 <cli> agents resume <id> [-w <ws>]
+<cli> agents import -w <ws> [--runtime <r>] [--json]          # conversations to bring in
+<cli> agents import -w <ws> --session <id> --persona <p>      # bring one in
 <cli> agents personas [--json]
 <cli> agents doctor [-w <ws>] [--json]  # can each runtime run here, and why not
 <cli> agents handback-check <file|->    # is a hand-back complete and plain (see Guardrails)
@@ -2052,12 +2061,30 @@ server scoped to its workspace.
   checkout dir (its `directory`, else `den-workspaces/<ws>`), capped by
   `agents.max_concurrent` (agents only: plain sessions never count). The id defaults to the persona's id; an id is
   unique in the distribution, so a second workspace's planner gets
-  `planner-<ws>` unless you give `--id`.
+  `planner-<ws>` unless you give `--id`. A persona that already has an
+  agent there, running or stopped, starts another: `planner-2`,
+  `planner-3`. A stopped agent is continued by Resume or Start fresh,
+  never by a new start. `--id` is exact: a running id is refused.
 - The **agent record**, `<stateDir>/agents/<id>.json` (0600), holds its id,
-  persona, runtime, model, workspace, cwd, session and times. It never holds
-  the environment or the command line. `list` reads it for persona, runtime
+  persona, runtime, model, workspace, cwd, session and times, and what it was
+  started with from the Start dialog: `version` (the model's, "latest" or
+  pinned), `permission` (`ask`, `edits` or `all`), `allow` (extra allowed
+  commands) and `overrides` (which of these differ from its persona). Start
+  fresh and Relaunch keep them. It never holds the environment, the command
+  line or a first instruction. `list` reads it for persona, runtime
   and model; a record whose session has gone is listed as `stopped` (after
   `stop`) or `ended`.
+- **Two name fields.** In the record, `sessionName` is the session's
+  handle, `<dist>-<ws>:<id>` (what `sessions attach` takes); it has meant
+  that since 0.4.0, and `displayName` is the name a person gave the agent.
+  In `agents list --json`, `GET /api/sessions` and the start and resume
+  answers (MCP `agent_resume`), `sessionTitle` is the name its session
+  shows: the latest of Den's rename and the runtime's own (Claude Code's
+  `/rename`, one pair of surrounding quotes dropped), absent when there is
+  none. The handle there is `name` (`/api/sessions`) or `session` (the
+  start and resume answers). 0.4.12 sent the name shown as `sessionName`;
+  read `sessionTitle` instead. Records are unchanged, so none written
+  before needs migrating.
 - `list` shows agents only: sessions with an agent record. A session from
   `sessions start` is not an agent; `sessions list` shows it.
 - `stop` sends its session TERM and marks it stopped. `resume` works only
@@ -2070,6 +2097,36 @@ server scoped to its workspace.
   exits non-zero, Den prints the exit code and its last lines (at most 10,
   secret-shaped values redacted) and exits 1.
 
+#### Bring in a conversation
+
+A conversation you started in a terminal outside Den (Claude Code, in the
+workspace's folder, a folder inside it, or a folder of one of its repos,
+a repo added by path outside it too) can become a Den agent. Agents ›
+**Bring in** lists them, newest first, with the persona list; `agents
+import -w <ws>` lists them too.
+
+- Den reads the runtime's own history: Claude Code's
+  `~/.claude/projects/<folder>/<id>.jsonl` (or under `CLAUDE_CONFIG_DIR`).
+  It reads only the first and last 64 KB of each file, for the folder it
+  ran in, its latest `/rename` and its first prompt. It never reads a whole
+  transcript, and it lists at most 50.
+- Bringing one in runs the runtime's resume (`claude --resume <id>`) in the
+  folder it ran in, as a new agent with the persona you pick. From then on
+  Den's token, MCP config, hooks, guards and audit trail apply. It is an
+  agent like any other: stop, resume, rename. The record notes
+  `broughtInAt`.
+- **One writer only.** A conversation written in the last minute is taken
+  to be still open in another terminal: "Still open in another terminal.
+  Close it there first" (HTTP 409 `open_elsewhere`). A conversation an
+  agent already continues is refused too (409 `already_agent`).
+- The agent's id is the persona's, or `<persona>-2`, `-3`… when that is
+  taken; `--id` sets one. An existing agent is never overwritten.
+- Only den-claude can bring one in for now. Other runtimes say "<runtime>
+  can't bring in a conversation yet".
+- Routes: `GET /api/workspaces/<ws>/conversations[?runtime=<r>]` and `POST
+/api/workspaces/<ws>/conversations/<id>/import` `{ persona, runtime?, id?
+}`. A person's only, unless MCP `agent_import` is opted in.
+
 ### On the Workspaces page
 
 The selected workspace's agents are listed under its repo table, one row
@@ -2104,13 +2161,78 @@ started. The workspace header counts them ("2 agents").
   workspace, and **Open** on a row with a session opens its terminal there.
 
 The routes: `GET /api/workspaces/<ws>/agents`, `POST
-/api/workspaces/<ws>/agents` (`{ persona, runtime?, model?, id? }`), `POST
-/api/workspaces/<ws>/agents/<id>/stop` and `…/resume`, and `GET
-/api/personas` (personas and runtimes). Errors are the usual
+/api/workspaces/<ws>/agents` (`{ persona, runtime?, model?, version?,
+permission?, allow?, instruction?, id? }`, see
+[The Start dialog](#the-start-dialog)), `POST
+/api/workspaces/<ws>/agents/<id>/stop` and `…/resume`, `POST
+/api/workspaces/<ws>/sessions` (a plain session), `GET /api/personas`
+(personas, runtimes with their models and permission translation, roles
+and categories), and the persona routes under
+[Personas](#personas). Errors are the usual
 `{ ok: false, error, code, requestId }`: `cap` (429),
 `conflict` (409, e.g. already running, or no resume), `not_found` (404),
 `exited_at_once` (502, with the session's last lines).
 
+### The Start dialog
+
+**+ Start agent** on the Agents tab (or `/agents?start=1`) opens the Start
+dialog:
+
+- **Persona**: a list you can search (name, role, description), with
+  category chips (only the categories that have personas) and source chips
+  (built-in, distribution, mine). With no filter set it is grouped by
+  category. Each row is the persona's name ("Rita (reviewer)", else its
+  id), its source badge and its one-line description, and "not installed"
+  when its runtime isn't. **Plain session** is pinned last: your login
+  shell in the workspace's folder, no agent. **What's a persona?** explains
+  the idea; **Details** shows the selected persona's instructions, runtime,
+  model and version, permission mode, role preset and extra commands.
+  **+ New persona**, **Duplicate** and (for your own) **Edit** open the
+  persona editor, and the dialog picks what you saved.
+- **Runtime** and **Workspace**. Installed runtimes come first; the rest
+  are listed, disabled, and named under the field ("Not found on this
+  machine: …"). A persona whose runtime isn't installed starts on the first
+  one that is, and the dialog says so. The line under the runtime says what
+  will run (see below).
+- **First instruction** (optional, up to 8000 characters): the agent's
+  first message. Den types it into the agent's session once the session is
+  ready (it has printed and gone quiet, or after 30 s), through the session
+  host, as a bracketed paste when the runtime asked for one, then Enter. It
+  is never a command-line argument and never stored; the audit log records
+  its length only.
+- **Advanced** (collapsed): **Model** and **Version** (the runtime's own
+  list; "Persona default" first), the **Permission mode** (Ask for
+  everything, Auto-approve edits in the worktree, Auto-approve all), the
+  role's command preset as chips, **Extra allowed commands** (plain command
+  prefixes, one per line, no patterns), and a preview of exactly what the
+  runtime will be given. A command a runtime can't take says "not supported
+  on <runtime>", and a pattern says "use a plain prefix"; neither is ever
+  dropped silently. "Edit raw runtime config…" is not there yet.
+
+What you change in Advanced applies to that launch only, and the session's
+row is tagged: "model: haiku", "pinned claude-opus-4-8", "auto-approve
+edits", "custom tools", the runtime, and always "auto-approve all" for an
+agent started so. An agent pinned to an older version says "newer
+available".
+
+Every field is checked on the server, not only in the page. The model and
+version must be ones the runtime lists, the permission one of `ask`,
+`edits` or `all`, and `allow` a list of at most 32 plain prefixes (letters,
+digits, single spaces and `. _ / : = @ % + , -`, at most 120 characters
+each). An unknown field is refused. A person's start only: an agent's
+token gets 403.
+
+**How each runtime takes the choices.** den-claude (Claude Code): a model is
+`--model <alias>` (`opus`, `sonnet`, `haiku`), a pinned version is `--model
+<full id>`. The model list is a catalog shipped with each Den release,
+because `claude` can't list its models. The permission mode is
+`--permission-mode` (`default`, `acceptEdits`, `bypassPermissions`), and
+each command prefix becomes two allow rules, `Bash(<prefix>)` and
+`Bash(<prefix> *)`, in the agent's settings file beside Den's deny rules
+(deny wins). Codex CLI, Gemini CLI, Grok Build and generic take no model,
+mode or commands from Den yet: the dialog says "not supported on <runtime>"
+and the start is refused if you set one.
+
 ### The Agents tab
 
 "Agents" in the rail (Develop, after Graph) is `/agents`: every session and
@@ -2181,7 +2303,10 @@ agent of the workspaces in view, and their terminals in the browser.
   pane header adds ` · <name>` after the runtime, and the tab, the list and
   ⌘K add it too, when it is not empty and says more than the agent's own
   name or persona. `GET /api/sessions`, `agents list --json` and the start
-  and resume answers (MCP `agent_resume`) carry it as `sessionName`.
+  and resume answers (MCP `agent_resume`) carry it as `sessionTitle`
+  (0.4.12: `sessionName`, which is the record's session handle). A
+  `/rename "api spike"` shows as api spike: one pair of quotes around the
+  whole name is dropped, for display only.
   Codex CLI, Gemini CLI and Grok Build have no name of their own yet. A
   catalog entry's `titleFromOsc: true` marks a runtime whose terminal
   title (OSC 0/2) names the session; no built-in runtime sets it, and the
@@ -2386,13 +2511,18 @@ a Claude Code agent file, read as it is, plus a few keys of Den's own:
 ```markdown
 ---
 name: planner # the id (or `id:`; default: the file name)
-description: Writes stories and their acceptance criteria. # or `role:`
+display_name: Rita # optional; shown as "Rita (reviewer)"
+role: planner # a role (see Roles); a sentence here is the description
+category: engineering # see Categories; default: the role's
+description: Writes stories and their acceptance criteria. # one line
 model: some-model # optional; `inherit` means none
+version: latest # or a pinned version of the model
+allowed_commands: [npm test] # extra plain prefixes allowed without asking
 tools: Read, Grep # hints for the runtime; Den restricts nothing with them
 standing: true # starts with its workspace (later slices)
 context: [docs/specs, the design system] # what to read first
 runtime: generic # default den-claude
-permission_mode: plan # den-claude only; default `default`
+permission_mode: ask # ask, edits or all (Claude Code's own modes still read)
 den_hooks: false # Den's guardrail hooks for this persona (see Guardrails)
 den_instructions: false # Den's shared instructions for this persona
 argv: ["some-cli", "--model", "{model}", "--mcp-config", "{mcp_config}"]
@@ -2402,8 +2532,9 @@ You are the planner. …
 ```
 
 Den ships a default pack: `planner` and `orchestrator` (standing), `fe-dev`,
-`be-dev`, `devops`, `reviewer` and `ux-designer`. Add your own packs, read in
-order after Den's; a persona with the same id replaces the earlier one:
+`be-dev` and `devops` (role `sde`), `reviewer`, `tester` and `ux-designer`
+(role `designer`, category Design). Add your own packs, read in order after
+Den's; a persona with the same id replaces the earlier one:
 
 ```yaml
 agents:
@@ -2416,6 +2547,53 @@ used without converting them. Files without front matter (a README) are
 skipped; two files with one id in a pack, or a pack that isn't a directory,
 are errors naming the file or the key.
 
+**Your own personas** live in `<stateDir>/personas/<id>.md` (0600), in the
+same format, read last: one wins over a pack's persona of the same id.
+Settings › Personas lists every persona with the Start dialog's search and
+chips: **View** (or **Edit** for your own), **Duplicate**, **Delete** (your
+own only) and **+ New persona**. A built-in or distribution persona is
+read-only; Duplicate makes your own copy to edit. "newer available" marks a
+persona pinned to an older version, with **Use latest** for your own. The
+routes: `GET /api/personas/<id>` (with its instructions), `POST
+/api/personas` (new), `POST /api/personas/<id>` (edit; 409 `read_only` for
+one that isn't yours) and `DELETE /api/personas/<id>`. Each field is
+checked: the role, category, runtime, model and version must be registered,
+the description one line of at most 200 characters, the name at most 40,
+the instructions at most 20000 characters with no control characters but
+newlines and tabs. An agent's token can't create, change or delete a
+persona (403); a person sets what agents may do.
+
+**Roles.** A role is a template and a key: default instructions, a
+permission mode and a command preset (read-only commands, allowed without
+asking). Den's roles are `planner`, `orchestrator`, `sde`, `reviewer`,
+`tester` and `designer`. Picking a role in New persona fills the form in,
+never over text you typed; a role adds nothing hidden to an agent's prompt.
+A distribution adds roles, and may extend a Den role's preset but not
+redefine it:
+
+```yaml
+agents:
+  roles:
+    copywriter:
+      description: Drafts release notes and site copy.
+      instructions: Draft copy in the house voice. Leave drafts for review.
+      mode: ask # ask, edits or all
+      preset: [vale]
+      category: marketing
+    reviewer:
+      preset: [semgrep] # added to Den's preset
+```
+
+**Categories** group personas in the Start list and Settings › Personas.
+Den's are Engineering, Design, Product, Marketing and Operations; a
+distribution adds more:
+
+```yaml
+agents:
+  categories:
+    - { id: legal, label: Legal }
+```
+
 ### Guardrails: hooks, shared instructions, hand-backs
 
 Every persona in Den's default pack gets two things with no setup: Den's

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monster-orange/den",
-  "version": "0.4.12",
+  "version": "0.4.14",
   "description": "Den: a local multi-repo dev orchestrator, HTTPS edge and E2E harness",
   "type": "module",
   "bin": {