@bastani/atomic 0.9.9 → 0.9.10-alpha.1

package/docs/sdk.md

@@ -432,6 +432,8 @@ const { session } = await createAgentSession({
 });
 ```
 
+`ModelRegistry` keeps synchronous reads for SDK and extension compatibility, while catalog refresh is asynchronous. Await `modelRegistry.refresh()` before reading `getAll()`, `find()`, or `getAvailable()` when a provider may update its catalog. The refresh result reports `aborted` and per-provider `errors`; successful providers publish their new catalogs even if another provider fails, and failed or timed-out providers retain their last-known models.
+
 If no model is provided:
 1. Tries to restore from session (if continuing)
 2. Uses default from settings
@@ -447,12 +449,16 @@ The package root exports the same context-window helpers and types used by the r
 
 ### API Keys and OAuth
 
+`AuthStorage` and `ModelRegistry` remain synchronous public SDK entry points. Token refresh is serialized under Atomic's credential-store lock, and the `authStorage` and `modelRegistry` session options remain available.
+
 API key resolution priority (handled by AuthStorage):
 1. Runtime overrides (via `setRuntimeApiKey`, not persisted)
 2. Stored credentials in `auth.json` (API keys or OAuth tokens)
 3. Environment variables (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, etc.)
 4. Fallback resolver (for custom provider keys from `models.json`)
 
+OAuth credentials may provide an API key, request headers, and a credential-specific `baseUrl`. Atomic applies all three to the request. In particular, GitHub Copilot enterprise and token-specific endpoints replace the static model URL without dropping retries, attribution headers, fast mode, or extension request hooks.
+
 ```typescript
 import { AuthStorage, ModelRegistry } from "@bastani/atomic";
 

package/docs/session-format.md

@@ -236,15 +236,15 @@ Emitted when the user selects a supported context-window size for the active mod
 
 ### CompactionEntry
 
-Created by `/compact`, RPC `compact`, and automatic compaction. The `summary` field contains the mechanically reconstructed verbatim transcript string, not generated summary prose. `firstKeptEntryId` points to the first ordinary message retained after the boundary.
+Created by `/compact`, RPC `compact`, and automatic compaction. The `summary` field contains the mechanically reconstructed verbatim transcript string, not generated summary prose. `firstKeptEntryId` is the first context-visible entry retained outside compaction, or `null` when no pre-boundary context-visible message is retained (including `preserve_recent: 0`).
 
 An entry is active only when `details.strategy` is exactly `"verbatim-lines"`:
 
 ```json
-{"type":"compaction","id":"c1","parentId":"m9","timestamp":"2026-07-13T10:00:00.000Z","summary":"[User]: fix the test\n(filtered 42 lines)\n[Assistant]: Fixed.","firstKeptEntryId":"m7","tokensBefore":51234,"details":{"strategy":"verbatim-lines","promptVersion":2,"rung":"standard","parameters":{"compression_ratio":0.5,"preserve_recent":2,"query":"fix the test"},"stats":{"linesBefore":812,"linesDeleted":417,"linesKept":395,"rangeCount":63,"tokensBefore":51234,"tokensAfter":24980,"percentReduction":51.2}}}
+{"type":"compaction","id":"c1","parentId":"m9","timestamp":"2026-07-13T10:00:00.000Z","summary":"[User]: fix the test\n(filtered 42 lines)\n[Assistant]: Fixed.","firstKeptEntryId":"m7","tokensBefore":51234,"details":{"strategy":"verbatim-lines","promptVersion":3,"rung":"planned","parameters":{"compression_ratio":0.5,"preserve_recent":2,"query":"fix the test"},"stats":{"linesBefore":812,"linesDeleted":417,"linesKept":395,"rangeCount":63,"tokensBefore":51234,"tokensAfter":24980,"percentReduction":51.2}}}
 ```
 
-On rebuild, Atomic emits the durable `summary` as a synthesized visible custom message, then emits original entries beginning at `firstKeptEntryId`. This exact string survives resume without rerunning a planner. `details.rung` is `"standard"`, `"critical"`, `"deterministic"`, or `"extension"`; `details.backupPath` is optional.
+On rebuild, Atomic emits the durable `summary` as a synthesized visible custom message, then emits original entries beginning at a string `firstKeptEntryId`. When the field is `null`, it emits no pre-boundary ordinary entries. In both cases, messages appended after the boundary are emitted. This exact state survives resume without rerunning a planner. Existing records with string IDs retain their behavior; `details.rung` is `"planned"` or `"extension"`, and `details.backupPath` is optional.
 
 Historical `compaction` records without `details.strategy: "verbatim-lines"` are retired summary-compaction records. They remain parseable and visible to audit/export tools but are inert in active LLM context.
 
@@ -332,8 +332,9 @@ Entries form a tree:
 `buildSessionContext()` walks the active branch from root to leaf and replays model, thinking-level, and context-window changes. It selects the latest `compaction` entry whose `details.strategy` is `"verbatim-lines"`.
 
 - With no active boundary, normal message, custom-message, and branch-summary entries are emitted verbatim.
-- With a boundary, Atomic emits its durable string as a custom-role `customType:"compaction"` message, then original messages from `firstKeptEntryId` onward, including messages appended after the boundary.
-- If a corrupt/foreign boundary's `firstKeptEntryId` is absent, Atomic emits the boundary followed by post-boundary messages rather than resurrecting all older content.
+- With a boundary whose `firstKeptEntryId` is a string, Atomic emits its durable string as a custom-role `customType:"compaction"` message, then original messages from that ID onward, including messages appended after the boundary.
+- With `firstKeptEntryId: null`, Atomic emits the boundary and post-boundary messages but no pre-boundary ordinary message.
+- If a corrupt/foreign boundary's non-null `firstKeptEntryId` is absent, Atomic emits the boundary followed by post-boundary messages rather than resurrecting all older content.
 - Legacy `context_compaction` entries and non-verbatim `compaction` entries are skipped as inert archival records.
 ## Parsing Example
 
@@ -425,7 +426,7 @@ for (const stage of stages.filter((session) => session.internal)) {
 - `appendThinkingLevelChange(level)` - Record thinking change
 - `appendContextWindowChange(contextWindow)` - Record context-window selection in tokens
 - `appendModelChange(provider, modelId)` - Record model change
-- `appendCompaction(compactedText, firstKeptEntryId, tokensBefore, details)` - Add a durable verbatim-line compaction boundary
+- `appendCompaction(compactedText, firstKeptEntryId, tokensBefore, details)` - Add a durable verbatim-line compaction boundary; pass `null` when no pre-boundary message is retained
 - `appendCustomEntry(customType, data?)` - Extension state (not in context)
 - `appendSessionInfo(name)` - Set session display name
 - `appendCustomMessageEntry(customType, content, display, details?)` - Extension message (in context)

package/docs/sessions.md

@@ -34,7 +34,7 @@ For the JSONL file format and SessionManager API, see [Session Format](/session-
 | `/tree` | Navigate the current session tree |
 | `/fork` | Create a new session from a previous user message |
 | `/clone` | Duplicate the current active branch into a new session |
-| `/compact` | Compact older transcript lines verbatim while preserving recent logical turns; see [Compaction](/compaction) |
+| `/compact` | Compact transcript lines verbatim while preserving exactly the configured number of newest context-visible messages; see [Compaction](/compaction) |
 | `/export [file]` | Export session to HTML |
 | `/share` | Upload as private GitHub gist with shareable HTML link |
 
@@ -42,7 +42,7 @@ For the JSONL file format and SessionManager API, see [Session Format](/session-
 
 `/resume` opens an interactive session picker for the current project. `atomic -r` opens the same picker at startup.
 
-When Atomic reconstructs a resumed session, the latest active verbatim `compaction` entry supplies a durable compacted transcript string followed by the original kept tail. Resume does not rerun a planner or re-derive omissions. Legacy logical-deletion `context_compaction` entries are inert archival records, so previously hidden content can re-enter context in sessions created by older versions.
+When Atomic reconstructs a resumed session, the latest active verbatim `compaction` entry supplies a durable compacted transcript string followed by the exact original kept tail. A zero-retention boundary stores `firstKeptEntryId: null` and replays no pre-boundary ordinary message. Resume does not rerun a planner or re-derive omissions. Legacy logical-deletion `context_compaction` entries are inert archival records, so previously hidden content can re-enter context in sessions created by older versions.
 
 In the picker you can:
 
@@ -55,6 +55,8 @@ In the picker you can:
 
 When available, Atomic uses the `trash` CLI for deletion instead of permanently removing files.
 
+The picker opens instantly: its header, search field, and loading indicator paint on the first frame, then sessions are discovered and parsed off the terminal's UI loop. Large session directories are scanned in cooperative batches and a single very large transcript is parsed in yielding chunks, so search, navigation, and cancel stay responsive and no individual session can freeze the picker while it loads. Closing the picker cancels any in-flight scan and discards stale results, so a slow load that finishes after you leave never updates the list.
+
 ### Internal (workflow) sessions
 
 Sessions created by workflow stage execution are marked as **internal** and are excluded from the standard `/resume`, `atomic -r`, and `--continue` history by default. This keeps the resume picker focused on your interactive coding sessions. Workflow stage sessions remain fully discoverable and resumable through the workflow-specific path: use `/workflow resume <runId>` (or the workflow tool's resume/status actions) to inspect and continue a workflow run and its stages. A workflow stage session can still be opened directly by passing its file path to `--session`.

package/docs/settings.md

@@ -137,7 +137,7 @@ Set `ATOMIC_SKIP_VERSION_CHECK=1` to disable the Atomic version update check. Us
 | `compaction.enabled` | boolean | `true` | Enable automatic verbatim line compaction |
 | `compaction.reserveTokens` | number | `16384` | Tokens reserved for the next model response; automatic threshold compaction begins before this reserve is consumed |
 | `compaction.compression_ratio` | number | `0.5` | Fraction of compactable transcript **lines to keep** (`0 < value < 1`) |
-| `compaction.preserve_recent` | number | `2` | Recent context-visible messages kept outside the compactable region; Atomic widens the cut to a user-turn start and always retains the final logical turn |
+| `compaction.preserve_recent` | number | `2` | Exact number of newest context-visible messages kept outside the compactable region; `0` keeps none |
 | `compaction.query` | string | last user message | Optional relevance focus for selecting older lines to retain |
 
 ```json
@@ -152,7 +152,7 @@ Set `ATOMIC_SKIP_VERSION_CHECK=1` to disable the Atomic version update check. Us
 }
 ```
 
-The model emits numbered line ranges only; Atomic reconstructs retained text mechanically. `preserve_recent` is enforced client-side and is not a provider parameter.
+The model emits numbered line ranges only; Atomic reconstructs retained text mechanically. `preserve_recent` is enforced client-side and is not a provider parameter. Atomic does not widen this exact message count to a user-turn boundary or force a final logical turn to remain outside compaction.
 
 ### Branch Summary
 

package/docs/subagents.md

@@ -37,9 +37,9 @@ Subagents now run and return their results directly. Atomic does not infer accep
 
 ## Foreground supervisor coordination
 
-When a foreground child sends `intercom.ask`, `intercom.send`, or `contact_supervisor` coordination, Atomic first probes for the exact foreground owner. Only an exact live child reserves the request; Atomic then sends a generation-scoped detach commit and waits for that child to acknowledge it before placing the message in the parent's model-visible steering queue. Unmatched and background-child messages retain the existing queued-until-idle behavior. Blocking `need_decision` and `interview_request` calls remain actionable through Intercom's pending/reply tracker, and the exact threaded reply resumes the retained child without delayed duplicate delivery.
+When a foreground child sends `intercom.ask`, `intercom.send`, or `contact_supervisor` coordination, Atomic first probes for the exact foreground owner. Only an exact live child reserves the request; Atomic then sends a generation-scoped detach commit and waits for that child to acknowledge it before placing the message in the parent's model-visible steering queue. This first-refusal ordering also applies when the parent is a busy workflow stage: detach completes before the request enters the stage AgentSession generation boundary, breaking the child-waits-for-reply / stage-waits-for-child cycle. Unmatched and background-child messages retain existing routing—ordinary parents queue until idle, while open workflow stages fall back to their native generation admission. Blocking `need_decision` and `interview_request` calls remain actionable through [Intercom](/intercom)'s pending/reply tracker, and the exact threaded reply resumes the retained child without delayed duplicate delivery.
 
-Only the matching foreground child releases the parent `subagent` tool. It stays alive under the normal watchdog, cancellation, drain, and stdio cleanup lifecycle; its eventual completion replaces the detached placeholder. Fire-and-forget `intercom.send` and `progress_update` also release foreground supervision promptly, but do not create a reply waiter.
+Only the matching foreground child can authorize release of the parent `subagent` tool. For a parallel foreground group, that accepted commit releases foreground supervision for every active sibling as one unit, so a long-running sibling cannot keep a blocking child request trapped behind the aggregate tool call; tasks still waiting behind the concurrency limit are skipped and never launched unsupervised. Active child processes stay alive under normal watchdog, cancellation, drain, and stdio cleanup ownership; each eventual completion replaces its detached placeholder. Run-owned worktrees remain attached until every detached child closes, then Atomic captures their diffs before cleanup. Fire-and-forget `intercom.send` and `progress_update` also release foreground supervision promptly, but do not create a reply waiter.
 
 Blocking coordination is race-safe: a session holds at most one outbound reply waiter, and concurrent blocking requests (parallel `intercom.ask` calls, or `intercom.ask` racing `contact_supervisor`) settle atomically. One request wins the reservation; every other concurrent call returns a normal "Already waiting for a reply" tool error without crashing the agent process or disturbing the pending ask. Cancellation and send failures release only their own waiter, and threaded replies still resolve the exact winning request.
 
@@ -129,6 +129,8 @@ Completion delivery distinguishes two compatibility surfaces. Intercom delivery
 
 Terminal background notifications preserve each child’s accepted Intercom order. Every broker message retains its sender timestamp and source session ID/name; bridged-child messages additionally carry their source run ID, agent, and child index. The deterministic child Intercom target and result-relay child mapping use the same run/agent/index identity, so duplicate display aliases remain isolated by run ownership. Before a paused, completed, or failed result is delivered, Intercom synchronously claims pre-terminal ordinary messages from those exact child targets and atomically admits the FIFO prelude plus terminal message as one ordered custom-message batch. A process-local bridge complements the extension event bus because lazily activated companion extensions may have distinct loader buses; duplicate bridge/event delivery is deduplicated by exact terminal identity even when the successful dispatch has no prelude. Failed dispatches remain retryable, and a resumed run’s later lifecycle terminal has a distinct identity. Terminal admission does not wait for a separate model turn, unrelated child entries remain independently queued, and exact threaded ask replies retain their correlation and timeout behavior.
 
+Inside workflow stages, completion delivery observes the stage generation boundary. A completion received before the boundary closes is queued through the stage AgentSession and processed before the stage publishes its terminal snapshot. A detached completion that arrives after close is routed once to the parent/main chat and cannot automatically reopen or append to the completed stage transcript. Producers that are still running do not hold the stage open, so background work remains non-blocking; explicit post-mortem stage chat is still available separately.
+
 When a workflow graph overlay is open, Atomic also publishes the live async subagent summary into the shared status surface. The below-editor async widget remains available when the workflow overlay is hidden, and the overlay statusline keeps the run count/state visible while the graph fills the terminal.
 
 ## Context and execution modes
@@ -146,6 +148,8 @@ Fresh child processes use normal Atomic package discovery when an agent omits `e
 
 Top-level parallel calls support up to 50 subagents after expanding each task's optional `count`. The extension's `parallel.maxTasks` setting defaults to 50 and can enforce a lower task limit; `parallel.concurrency` independently controls how many of those children run at once.
 
+Subagent tasks, parallel/chain items, and the top-level call accept a `group` field that sets the spawned child's [Intercom](/intercom) home group, so same-group subagents can intercom each other while staying isolated from other groups. A named string joins that group; `true` auto-generates one shared UUID group per parallel set (shared across all items in that set). Precedence is `explicit subagent group > inherited current-session (stage) group > env ATOMIC_INTERCOM_GROUP > config > "default"`. When a subagent does not specify a group, it **inherits the launching session's group** — read race-safely from the session, not from global env — so subagents spawned by a grouped workflow stage automatically join that stage's group and can coordinate with the stage and its sibling subagents. The child intercom group is applied only when the child actually has intercom access (the peer `intercom` tool or the subagent-only `contact_supervisor` tool); a child without intercom is never placed into a group. `contact_supervisor` still reaches the supervisor across group boundaries because Atomic requests a broker capability before spawn and binds the child's registration to the issuing supervisor. Foreground and single-child paths use exact child scopes; asynchronous chains use bounded per-child slots so indexes shifted by dynamic fanout remain valid. Capability environment values are explicitly cleared for descendants without a fresh grant, and parent-held grants are restored after reconnects. The lightweight Intercom wrapper lazy-loads the authorization provider; provider failures propagate and abort launch, while hosts without a provider omit supervisor metadata instead of exposing a broken `contact_supervisor` channel.
+
 When a subagent call, parallel task, chain step, or background run uses a `cwd`, Atomic validates that working directory before starting the child runtime. Missing or non-directory paths are reported as `cwd` problems instead of lower-level process-spawn errors, so failures point at the requested child workspace rather than at the runtime binary.
 
 Single-agent calls also accept `reads: string[] | false`. Atomic prepends those files as read context for foreground and background execution through the same path resolver, including `/run agent[reads=a.md+b.md]`. Relative entries resolve against the effective child `cwd` (including a relative top-level `cwd` resolved from the parent); absolute entries are unchanged. Invalid values fail before either child runtime starts.
@@ -257,5 +261,6 @@ Because the effort travels with each model string, every primary and fallback ca
 ## Related docs
 
 - [Workflows](/workflows) for multi-stage reusable automation.
+- [Intercom](/intercom) for cross-session messaging and supervisor escalation.
 - [Skills](/skills) for reusable instructions invoked with `/skill:<name>`.
 - [Settings](/settings) for user and project configuration.

package/docs/tui.md

@@ -99,6 +99,65 @@ pi.on("session_start", async (_event, ctx) => {
 
 Pass `{ signal }` to `ctx.ui.custom()` when the UI belongs to an abortable operation. If the signal aborts, Atomic dismisses the custom UI and rejects the returned promise with the signal reason. For overlays, use `options.onHandle` to receive an overlay handle for programmatic visibility control.
 
+In Atomic's default interactive mode, the component instance remains in the isolated engine child. The terminal host caches rendered lines and forwards input asynchronously, so `render()` and `handleInput()` must not depend on direct access to host process objects. The remote bridge preserves pi-tui's key-release contract: release events are filtered unless the child component sets `wantsKeyRelease = true`, matching a directly mounted component. Return values passed to `done()` must be JSON-safe.
+
+### Host terminal modes from an isolated component
+
+Because the component runs in the engine child — whose stdout is the JSONL transport, not a TTY — writing raw terminal escape sequences to `process.stdout` from `render()`/`handleInput()` is a no-op and never reaches the real host terminal. For the two host-terminal modes an overlay commonly needs, the factory `tui.terminal` exposes typed, allowlisted setters that the host applies to the real TTY over the engine protocol:
+
+```typescript
+await ctx.ui.custom((tui, theme, keybindings, done) => {
+  tui.terminal.setMouseScrollTracking?.(true); // enable SGR mouse-scroll reporting on the host TTY
+  tui.terminal.setAutowrap?.(false);           // disable autowrap (DECAWM) — Windows terminals only
+  return new MyOverlay({ onClose: done });
+}, { overlay: true });
+```
+
+These are the only terminal controls exposed; arbitrary child bytes are never forwarded to the terminal. The host resets any mode a component enabled when the overlay hides, closes, is disposed, or when the engine child crashes/restarts, so a stranded child can never leave the terminal in mouse-reporting or autowrap-off mode. On non-isolated hosts and test seams the setters are absent, and callers should fall back to writing escape sequences to their own `process.stdout`.
+
+### Host-native session picker
+
+Remote-rendered components pay one host⇄child round trip per keypress under engine isolation. For session-style list pickers, the `ctx.ui.hostSessionPicker(request)` capability avoids that entirely: the terminal host mounts the real built-in `SessionSelectorComponent` and feeds it JSON-safe rows, so arrow-key navigation and search stay host-local and survive extension event-loop stalls. Only semantic events cross the host⇄extension boundary: the extension pushes row `update`s and `error`s (and may `close()` the picker); the host reports selection, cancel, and confirmed Ctrl+D deletes.
+
+Every interactive host implements the same API — non-isolated mode mounts the selector directly in-process (no IPC at all), isolated mode routes it over the engine session-picker protocol channel — so callers never branch on the mode. The member is absent only on non-interactive surfaces (headless RPC, print); fail with an actionable error there instead of degrading to a hand-rolled picker.
+
+```typescript
+const picker = ctx.ui.hostSessionPicker?.({
+  sessions: rows, // HostSessionPickerRow[]: SessionInfo with createdAt/modifiedAt epoch millis
+  showRenameHint: false,
+  onDelete: async (path) => {
+    // Deletion is extension-owned: the host keeps the row until you reply.
+    const outcome = await remove(path);
+    if (outcome.ok) picker!.update(rowsWithout(path));
+    else picker!.error(outcome.message);
+  },
+});
+if (!picker) throw new Error("This command requires an interactive session picker");
+picker.update(await loadMoreRows()); // merge late rows into the open picker
+const path = await picker.result;    // selected row's path, or undefined on cancel
+```
+
+The bundled workflows extension's `/workflow resume` picker is built exclusively on this channel.
+
+### Host-native input form
+
+Use `ctx.ui.hostInputForm(request)` for structured inline forms whose keyboard handling must remain responsive under interactive-engine isolation. The terminal host mounts and focuses the real form in the bottom editor slot (`overlay: false`); Tab/Shift+Tab, arrows, text editing, configured keybindings, Enter, Escape, and Ctrl+C are handled entirely in the host process. In isolated mode only the JSON-safe open request and the final submit/cancel event cross the engine boundary. Non-isolated mode mounts the same component directly.
+
+```typescript
+const values = await ctx.ui.hostInputForm?.({
+  title: "Release",
+  fields: [
+    { name: "version", type: "string", required: true, initialValue: "" },
+    { name: "channel", type: "select", choices: ["stable", "beta"], initialValue: "stable" },
+  ],
+});
+if (values === undefined) return; // Escape, Ctrl+C, teardown, or close
+```
+
+Field types are `string`, `text`, `number`, `integer`, `boolean`, and `select`. Initial and returned values are raw strings; the caller owns domain coercion. Every current interactive Atomic host exposes the optional capability, while headless RPC and print surfaces omit it. Keep a legacy fallback only when compatibility with older hosts is required.
+
+The bundled `/workflow <name>` input picker uses this channel and retains its older custom-editor/`ctx.ui.custom()` paths only as compatibility fallbacks.
+
 ## Overlays
 
 Overlays render components on top of existing content without clearing the screen. Pass `{ overlay: true }` to `ctx.ui.custom()`:
@@ -448,7 +507,7 @@ Set `ATOMIC_TUI_WRITE_LOG` to capture the raw ANSI stream written to stdout.
 ATOMIC_TUI_WRITE_LOG=/tmp/tui-ansi.log atomic
 ```
 
-Atomic vendors TUI components through the installed `@earendil-works/pi-tui` dependency; this monorepo does not include the upstream TUI test source tree.
+Atomic vendors TUI components through the installed `@earendil-works/pi-tui` dependency.
 
 ## Performance
 
@@ -760,7 +819,7 @@ ctx.ui.setWorkingIndicator({ frames: [] });
 ctx.ui.setWorkingIndicator();
 ```
 
-This only affects the normal streaming working indicator. Compaction and retry loaders keep their built-in styling. Custom frames are rendered verbatim, so extensions must add their own colors when needed.
+This only affects the normal streaming working indicator. Compaction and retry loaders keep their built-in styling. During successful post-tool autocompaction, Atomic temporarily replaces the working indicator with the compaction loader and restores the working indicator before the same stream continues; no additional user input is required. Custom frames are rendered verbatim, so extensions must add their own colors when needed.
 
 **Examples:** [working-indicator.ts](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/examples/extensions/working-indicator.ts)
 

package/docs/usage.md

@@ -39,7 +39,7 @@ Type `/` in the editor to open command completion. Extensions can register custo
 | `/model` | Switch models |
 | `/scoped-models` | Enable/disable models for CTRL+P cycling |
 | `/fast` | Toggle Codex fast mode for chat and workflow stages when `openai/*` or `openai-codex/*` models are available |
-| `/workflow` | List/run workflows; manage runs (connect/inspect/pause/interrupt/resume/kill); reload workflow resources |
+| `/workflow` | List/run workflows; manage runs (connect/inspect/pause/interrupt/quit/resume); reload workflow resources |
 | `/settings` | Thinking level, theme, message delivery, transport |
 | `/resume` | Pick from previous sessions |
 | `/new` | Start a new session |
@@ -93,7 +93,7 @@ Useful session commands:
 - `/tree` navigates the in-file session tree and can summarize abandoned branches.
 - `/fork` creates a new session from an earlier user message.
 - `/clone` duplicates the current active branch into a new session file.
-- `/compact` uses verbatim line compaction: the model selects one-based numbered ranges to delete, Atomic validates them, and retained text is reconstructed mechanically with `(filtered N lines)` markers. Recent logical turns remain ordinary messages.
+- `/compact` uses verbatim line compaction: the model selects one-based numbered ranges to delete, Atomic validates them, and retained text is reconstructed mechanically with `(filtered N lines)` markers. Exactly the configured number of newest context-visible messages remains ordinary; the default is two and zero preserves none.
 
 See [Sessions](/sessions) and [Compaction](/compaction) for details.
 
@@ -122,7 +122,7 @@ Use `/export [file]` to write a session to HTML.
 
 Use `/share` to upload a private GitHub gist with a shareable HTML link.
 
-If you use Atomic for open source work and want to publish sessions for model, prompt, tool, and evaluation research, use an Atomic-owned workflow or your team's dataset process. Upstream Pi session-sharing utilities may still be useful for historical context, but they are not the primary Atomic publication path.
+Treat exported and shared sessions as sensitive: transcripts can contain source code, file paths, credentials, and other private data from your session. Review a session before sharing it, and only upload transcripts you are comfortable making accessible to anyone with the link.
 
 ## CLI Reference
 
@@ -139,6 +139,7 @@ atomic uninstall <source> [-l]     # Alias for remove
 atomic update [source|self|atomic] # Update Atomic only, or one package source
 atomic update --all                # Update Atomic and packages; reconcile pinned git refs
 atomic update --extensions         # Update packages only; reconcile pinned git refs
+atomic update --models             # Force-refresh authenticated provider model catalogs
 atomic update --self               # Update Atomic only
 atomic update --extension <src>    # Update one package
 atomic list                        # List installed packages
@@ -292,10 +293,10 @@ atomic --tools read,search,find,ls -p "Review the code"
 | `PI_CACHE_RETENTION` | Provider/upstream-specific prompt-cache retention knob; set to `long` where supported |
 | `VISUAL`, `EDITOR` | External editor for CTRL+G |
 
-`PI_*` aliases are also supported for app-specific `ATOMIC_*` variables for legacy compatibility. For example, intercom honors `PI_CODING_AGENT_DIR` when `ATOMIC_CODING_AGENT_DIR` is unset and still reads legacy `~/.pi/agent/intercom/config.json` when the Atomic config is absent. `PI_CACHE_RETENTION` is not one of those aliases and has no `ATOMIC_*` equivalent. Use `PI_CACHE_RETENTION=long` when configuring prompt-cache retention for providers/upstreams that support long-lived caches. Intercom's default broker starter works across Node-based installs, Bun source checkouts, and standalone Atomic binaries without requiring `npx`, `tsx`, or `bun` to be present on `PATH`; custom broker commands remain explicit opt-in overrides.
+`PI_*` aliases are also supported for app-specific `ATOMIC_*` variables for legacy compatibility. For example, [Intercom](/intercom) honors `PI_CODING_AGENT_DIR` when `ATOMIC_CODING_AGENT_DIR` is unset and still reads legacy `~/.pi/agent/intercom/config.json` when the Atomic config is absent. `PI_CACHE_RETENTION` is not one of those aliases and has no `ATOMIC_*` equivalent. Use `PI_CACHE_RETENTION=long` when configuring prompt-cache retention for providers/upstreams that support long-lived caches. Intercom's default broker starter works across Node-based installs, Bun source checkouts, and standalone Atomic binaries without requiring `npx`, `tsx`, or `bun` to be present on `PATH`; custom broker commands remain explicit opt-in overrides.
 
 ## Design Principles
 
-Atomic keeps the core CLI small, while this distribution bundles first-party package extensions for workflows, subagents, MCP, web access, and intercom. Other workflows can still be installed as extensions or packages, or handled externally with tools such as containers and tmux.
+Atomic keeps the core CLI small, while this distribution bundles first-party package extensions for workflows, subagents, MCP, web access, and [intercom](/intercom). Other workflows can still be installed as extensions or packages, or handled externally with tools such as containers and tmux.
 
 For the full rationale, read the [blog post](https://mariozechner.at/posts/2025-11-30-pi-coding-agent/).