docs: update documentation to clarify tentacle structure, terminal lifecycle, and inter-agent messaging

Author: hesamsheikh

README.md

@@ -96,10 +96,13 @@ For the current model, see [Orchestrating Child Agents](docs/guides/orchestratin
 
 ## How It Works
 
-1. Create a tentacle for a scoped slice of work.
-2. Store context, notes, and `todo.md` inside that tentacle so the agent has durable, local guidance.
-3. Run one or more agent terminals against that tentacle, and delegate child work from the task list when needed.
-4. Use the local API and web UI to monitor sessions, messages, transcripts, and worktree state.
+Octogent separates three concerns that usually get mixed together in a pile of terminals:
+
+1. **Context** lives in `.octogent/tentacles/<tentacle-id>/`. `CONTEXT.md` explains the area, `todo.md` supplies executable work items, and extra markdown files hold notes or handoffs.
+2. **Execution** lives in terminal records and PTY sessions managed by the local API. A terminal can attach to an existing tentacle, and several terminals can share one tentacle during swarm work.
+3. **Isolation** is optional. Shared terminals run in the main workspace; worktree terminals run under `.octogent/worktrees/<worktree-id>/` on `octogent/<worktree-id>` branches.
+
+Deck reads the tentacle files directly, parses checkbox items from `todo.md`, and uses incomplete items to generate worker prompts. Claude hooks feed the API with agent state, transcript, and idle events so the UI can show more than raw terminal output.
 
 ## Quick start
 

docs/concepts/mental-model.md

@@ -2,23 +2,38 @@
 
 This page is for the exact model behind Octogent. The README is the pitch. This page is the boundary map.
 
-## The main pieces
-
-- the **developer** defines the jobs and reviews the output
-- a **tentacle** holds the local context for one job
-- a **terminal** is one live Claude Code session
-- a **worker** is a terminal assigned to a narrower piece of work
-- a **parent** is a terminal coordinating one or more workers
-- a **channel** is a short-lived coordination path between terminals
+## Architectural layers
+
+Octogent separates durable work context from live terminal execution.
+
+```mermaid
+flowchart TD
+  Human[Developer] --> Deck[Deck and Canvas UI]
+  Deck --> API[Local API]
+  API --> Files[".octogent/tentacles/*"]
+  API --> State["~/.octogent/projects/<id>/state/*"]
+  API --> PTY[PTY-backed agent sessions]
+  PTY --> Hooks[Claude hooks]
+  Hooks --> API
+```
+
+- the **developer** defines boundaries, reviews output, and decides what lands
+- a **tentacle** is the durable job context: markdown files, todos, notes, and handoff state
+- a **terminal** is the runtime record plus, when active, one PTY-backed agent session
+- a **worker** is a terminal assigned to one narrower task, usually a todo item
+- a **parent** is a terminal that coordinates workers and performs final review or merge work
+- a **channel** is an in-memory queue used to inject short messages into live terminals
 
 ## Tentacle vs terminal
 
 These are different things.
 
 - a **tentacle** is a folder with agent-readable files
-- a **terminal** is a running session
+- a **terminal** is a runtime object that can attach to one tentacle
+
+Multiple terminals can point at the same tentacle. Swarm workers use that property: each worker gets the same context files, but each terminal has its own identity, transcript, lifecycle state, and optional worktree.
 
-Multiple terminals can point at the same tentacle. That matters for swarm work, because several workers may need the same local context while still remaining separate sessions.
+This is why terminal IDs and tentacle IDs are not interchangeable. A terminal can be named `api-runtime-swarm-2` while still using the `api-runtime` tentacle context.
 
 ## Tentacle vs worktree
 
@@ -34,6 +49,8 @@ A tentacle can be used with:
 
 The tentacle decides *what the job is about*. The worktree decides *where the code changes happen*.
 
+In shared mode, the PTY starts in the main workspace. In worktree mode, the API creates `.octogent/worktrees/<worktree-id>/` on branch `octogent/<worktree-id>` and starts the PTY there. The agent-facing context still stays in `.octogent/tentacles/<tentacle-id>/`.
+
 ## What belongs in files
 
 The durable source of truth should live in files inside the tentacle.
@@ -46,28 +63,34 @@ That includes:
 
 If another agent needs to understand the job later, the important information should already be there without depending on one old chat thread.
 
+Deck reads these files directly. It parses the first heading and first non-empty paragraph of `CONTEXT.md` for display metadata, lists other markdown files as vault files, and parses checkbox lines in `todo.md` for progress and worker assignments.
+
 ## What belongs in runtime state
 
 The runtime owns:
 
-- live terminal sessions
+- terminal records and lifecycle state
+- live PTY sessions
 - websocket transport
 - UI state
 - transcripts
 - message delivery state
 
-That data helps the app run, but it is not the same thing as the durable job context.
+That data helps the app run, but it is not the same thing as the durable job context. Terminal records survive API restarts. PTY sessions, WebSocket clients, and channel queues do not.
+
+On startup, Octogent reloads terminal records from `tentacles.json`. If a record says it was running, Octogent cannot reattach to the old in-memory PTY, so the record is reconciled to `stale` with a lifecycle reason.
 
 ## How delegation is supposed to work
 
 The expected flow is:
 
 1. the developer or a parent agent defines a job boundary
 2. the tentacle files capture the local context
-3. `todo.md` breaks the job into executable items
-4. one or more child terminals take those items
-5. workers report status through files and short messages
-6. the parent or human reviews the result
+3. `todo.md` breaks the job into executable checkbox items
+4. Deck or the CLI creates terminals from those items
+5. each worker receives a prompt generated from the tentacle context path, todo text, workspace mode, and parent terminal ID when present
+6. workers report status through short channel messages and by leaving durable notes in files
+7. the parent or human reviews the result and updates `todo.md`
 
 If the boundary is vague, the orchestration gets worse. Octogent helps organize work, but it does not rescue a poorly defined job.
 

docs/concepts/runtime-and-api.md

@@ -15,22 +15,28 @@ flowchart TD
   Runtime --> Hooks[Claude hook ingestion]
 ```
 
-## What the API does
+## Runtime responsibilities
 
-- starts and restores terminal metadata
-- serves the web UI when bundled assets are available
-- manages PTY-backed terminal sessions
-- creates worktrees for isolated terminals
-- persists UI state and conversation state
-- reads tentacle files and todo progress
-- accepts hook events from Claude Code
-- exposes channels for inter-agent messages
+The API process owns the moving parts that cannot live in markdown:
+
+- terminal registry loading, migration, and persistence
+- PTY lifecycle and scrollback
+- WebSocket upgrades for terminal IO and terminal list events
+- Claude hook installation and ingestion
+- worktree creation and cleanup for isolated terminals
+- transcript capture and conversation export
+- in-memory channel queues
+- Deck file operations over `.octogent/tentacles/`
+- UI state persistence
 
 ## Transport model
 
-- HTTP for CRUD, metadata, and snapshots
-- WebSocket for live terminal IO
-- file-backed state for persistence
+- HTTP handles CRUD, snapshots, prompt resolution, setup checks, and file-backed operations
+- `WS /api/terminals/:terminalId/ws` attaches a browser terminal to one PTY session
+- `WS /api/terminal-events/ws` broadcasts terminal-created, terminal-updated, terminal-deleted, and state-change events
+- file-backed state is the restart boundary for terminal records, UI state, transcripts, deck metadata, and monitor/cache data
+
+Terminal WebSockets do not own the PTY. They are clients attached to a PTY session owned by the API process. When a browser reloads, a new WebSocket can receive scrollback during the idle grace window. When the API restarts, the PTY is gone.
 
 ## Security defaults
 
@@ -46,6 +52,39 @@ flowchart TD
 - PTY sessions do not survive API restarts
 - terminal records persisted as `running` are reconciled to `stale` on startup when no live Octogent session owns them
 
+The terminal registry is `tentacles.json` for historical reasons. Current records are terminals, not tentacles. A terminal record stores identity, tentacle ID, optional worktree ID, parent terminal ID, workspace mode, display name, lifecycle fields, and UI-related metadata.
+
+Deck metadata is separate from tentacle markdown. `deck.json` stores display/status details that should not be mixed into `CONTEXT.md` or `todo.md`.
+
+## Terminal lifecycle
+
+Creating a terminal writes a registry record first. If an initial prompt is provided, the runtime immediately starts a PTY session. Otherwise, the PTY starts when a WebSocket or direct listener attaches.
+
+When a PTY starts, Octogent:
+
+1. resolves the working directory from the terminal workspace mode
+2. spawns the user's shell through `node-pty`
+3. injects the configured agent bootstrap command
+4. optionally pastes and submits an initial prompt
+5. writes transcript events and keeps bounded scrollback in memory
+6. broadcasts state updates to attached clients
+
+Stopping or killing a terminal tears down the active PTY and updates lifecycle metadata. Deleting a terminal also cascades to child terminals and removes worktrees for worktree-backed records.
+
+## Hook mechanism
+
+For Claude-backed terminals, Octogent writes hooks into the target `.claude/settings.json`. The hooks call back into the local API and provide state transitions that terminal output alone cannot reliably express.
+
+Hooks currently feed these mechanisms:
+
+- `UserPromptSubmit` marks the terminal active and can auto-name generated terminals from the first prompt
+- `PreToolUse` records the current tool and marks user-question waits
+- `Notification` marks permission waits and idle prompts
+- `Stop` parses Claude transcript data into stored conversations and releases the idle keep-alive
+- `PostToolUse` for `Edit|Write` feeds code-intel events
+
+Channel delivery is also tied to hooks. Messages are queued in memory and injected when a target session is idle, including after idle or stop hook events.
+
 ## Main API groups
 
 - terminals and snapshots

docs/concepts/tentacles.md

@@ -2,7 +2,7 @@
 
 Tentacles are the core abstraction in Octogent.
 
-## Definition
+## What a tentacle is
 
 A tentacle is a folder under `.octogent/tentacles/<tentacle-id>/` that stores agent-readable markdown files.
 
@@ -13,9 +13,23 @@ The minimum useful files are:
 
 Additional markdown files are allowed and are surfaced as tentacle vault files in the app.
 
+The important part is that the folder is agent-facing. It is the durable context that a terminal agent can read, edit, and hand off to another terminal.
+
+## How Deck reads a tentacle
+
+Deck does not maintain a separate database copy of the tentacle context. It scans `.octogent/tentacles/` and derives most of the view from files:
+
+- a folder is considered a tentacle only when it contains `CONTEXT.md`
+- the first `# Heading` in `CONTEXT.md` becomes the display name
+- the first non-empty paragraph after that heading becomes the description
+- every other `.md` file becomes a vault file, with `todo.md` sorted first
+- checkbox lines in `todo.md` become progress and worker inputs
+
+Deck-specific metadata such as color, status, octopus appearance, paths, and tags lives separately in runtime state. That keeps UI preferences out of the agent-facing markdown files.
+
 ## What a tentacle is for
 
-Use a tentacle when you want a durable context layer for one slice of the codebase or one track of work.
+Use a tentacle when one slice of the codebase or one track of work needs its own local operating context.
 
 Examples:
 
@@ -36,7 +50,7 @@ Examples:
 - what not to break
 - any Claude Code skills that are especially useful for this tentacle, when relevant
 
-The first heading and first non-empty paragraph are used by the runtime as the display name and description.
+The first heading and first non-empty paragraph are runtime-significant. Keep them stable and useful because they become the name and description shown in Deck, Canvas, prompt summaries, and terminal creation flows.
 
 When a tentacle has suggested Claude Code skills, Octogent appends a managed block at the bottom of `CONTEXT.md`:
 
@@ -50,6 +64,8 @@ You can use these skills if you need to.
 <!-- octogent:suggested-skills:end -->
 ```
 
+The managed block is rewritten by the API when suggested skills change. Put human-authored architecture notes outside that block.
+
 ## What goes in `todo.md`
 
 `todo.md` should contain markdown checkbox items:
@@ -64,6 +80,10 @@ You can use these skills if you need to.
 
 The runtime parses checkbox lines and computes progress.
 
+Only lines that match `- [ ] text` or `- [x] text` are treated as todo items. Their order matters because swarm creation uses the parsed item index when it creates worker terminal IDs such as `<tentacle-id>-swarm-0`.
+
+When the UI toggles, edits, adds, or deletes todos, it rewrites `todo.md`. There is no hidden todo store.
+
 ## Tentacles and delegation
 
 The point of a tentacle is not only documentation. It is operational context.
@@ -75,6 +95,8 @@ A worker attached to a tentacle can:
 - use the todo list as a work queue
 - hand work to child agents without rebuilding context from scratch
 
+When a todo item is solved from Deck, Octogent reads the item text, resolves a worker prompt template, and creates a terminal attached to the same tentacle. For swarm runs, incomplete todo items become workers, and larger swarms get a parent coordinator terminal that supervises completion.
+
 ## Tentacles and worktrees
 
 Tentacles are not the same thing as worktrees.
@@ -83,3 +105,12 @@ Tentacles are not the same thing as worktrees.
 - a worktree is an isolated git checkout for a terminal
 
 You can use a tentacle with shared workspace terminals or worktree terminals.
+
+In shared mode, all terminals operate in the main workspace, so the context boundary is social and procedural. In worktree mode, each terminal can get a separate checkout under `.octogent/worktrees/`, but it still reads the same tentacle folder for instructions and todos.
+
+## Failure boundaries
+
+- deleting a tentacle removes its agent-facing files, but terminal records are separate runtime state
+- restarting the API preserves terminal metadata and transcripts but not live PTYs
+- channel messages do not persist, so durable handoffs belong in tentacle markdown
+- worktree branches are tied to worktree-backed terminals, not to the tentacle folder itself

docs/guides/inter-agent-messaging.md

@@ -2,9 +2,11 @@
 
 Octogent has a simple local channel system for messages between terminals.
 
-## What it is for
+## What channels are
 
-Use channel messages for short coordination:
+Channels are in-memory queues keyed by target terminal ID. Sending a message does not write to the target tentacle files and does not create a persistent notification record.
+
+Use them for short coordination:
 
 - ask for review
 - report completion
@@ -13,6 +15,23 @@ Use channel messages for short coordination:
 
 It is not a replacement for proper context files.
 
+## Delivery model
+
+When a message is sent, Octogent:
+
+1. verifies the target terminal record exists
+2. appends the message to that terminal's in-memory queue
+3. marks it as undelivered
+4. injects pending messages into the target PTY when the target session is idle
+
+Delivered messages are written into the terminal input as lines like:
+
+```text
+[Channel message from <from-terminal-id>]: <content>
+```
+
+If the target terminal is not running, the message waits in memory until that session exists and becomes idle. If the API restarts first, the message is lost.
+
 ## CLI usage
 
 Send a message:
@@ -21,6 +40,14 @@ Send a message:
 octogent channel send <terminal-id> "Need review on the parser change"
 ```
 
+When one terminal is messaging another, pass the sender explicitly:
+
+```bash
+octogent channel send <target-terminal-id> "DONE: parser change is ready" --from <sender-terminal-id>
+```
+
+If `--from` is omitted, the CLI uses `OCTOGENT_SESSION_ID` when it is available.
+
 List messages:
 
 ```bash
@@ -37,6 +64,8 @@ octogent channel list <terminal-id>
 - messages are stored in memory
 - messages do not persist across API restarts
 - delivery state is tracked by the API
+- idle and stop hook events can trigger delivery
+- listing messages shows queued and delivered messages for the current API process
 
 ## Practical rule