feat(onboarding): first-run CTA and workflow-routing handoff

README.md

@@ -225,7 +225,7 @@ Workflows define the executable loop: inputs, stages, branches, parallelism, ret
 | `open-claude-design`     | End-to-end design generation: interviews for output type/references, discovers your design system, generates from a prompt, refines with feedback, and exports a handoff directory.                                                                                                                                                                                        | `/workflow open-claude-design prompt="Team activity feed prototype using ./mocks/feed.png as a reference"`                                                                                    |
 | _author your own_        | Anything outside the built-ins: issue-to-PR, review-to-merge, migration, triage, release, compliance, or team-specific review pipelines. Describe the process in natural language and Atomic can scaffold a typed `workflow({...})` file with CLI inputs.                                                                                                                   | _"Create a reusable workflow that takes an issue, writes a plan, creates a branch, runs implementation and review stages, runs tests and lint, then stops for approval before final output."_ |
 
-Run `/workflow list` to see installed workflows and `/workflow inputs <name>` for input schemas. `/workflow status <id>`, `/workflow connect <id>`, and `/workflow resume <id>` manage running or paused runs. Runnable references live in [`packages/coding-agent/examples/`](./packages/coding-agent/examples).
+Run `/workflow list` to see installed workflows and `/workflow inputs <name>` for input schemas. `/workflow status <id>`, `/workflow connect <id>`, and `/workflow resume <id>` manage running or paused runs. First-run `goal`/`ralph` handoffs print the status/connect commands with the run id; use connect to watch, attach, and steer, or ask in the current chat for status or steering at any point. Runnable references live in [`packages/coding-agent/examples/`](./packages/coding-agent/examples).
 
 ### 2. Skills
 

packages/coding-agent/CHANGELOG.md

@@ -9,6 +9,8 @@
 
 ### Added
 
+- Added one-time first-run onboarding that explains Atomic workflows, uses an onboarding editor placeholder, lets users opt into normal chat with `/chat`, preserves other slash commands, saves a pre-login pasted task in memory only, and hands the first ready ticket/spec/task to the normal coding-agent session with `goal`/`ralph` workflow-routing guidance.
+- Added first-run onboarding routing guidance that raises the parent session to high reasoning when supported, asks the coding agent to first make a text-only scope estimate from tickets/GitHub issues/specs, routes directly when the task is clearly tiny or small with high confidence, and only uses targeted read-only `codebase-locator`/`codebase-analyzer`/`codebase-pattern-finder` probing when referenced context must be read or scope is medium, large, unclear, risky, or not obviously tiny before choosing `goal` or `ralph`.
 - Added a first-class `search` built-in and exposed `find`/`search` in normal coding sessions ([#1483](https://github.com/bastani-inc/atomic/issues/1483)).
 - Added hashline snapshot anchors across `read`, `search`, `write`, and successful `edit` results, plus hashline line-range/block/multi-section edit scripts with stale-tag safety checks and snapshot-based recovery for non-overlapping file drift, empty-replace validation, and fresh post-mutation tags for follow-up edits ([#1483](https://github.com/bastani-inc/atomic/issues/1483)).
 - Added disabled-by-default `bashInterceptor.enabled` settings support with built-in shell anti-pattern rules, a `/settings` **Bash Interceptor** toggle, and optional `user_bash` extension routing, without changing the default local-execution behavior ([#1483](https://github.com/bastani-inc/atomic/issues/1483)).
@@ -17,10 +19,20 @@
 
 ### Changed
 
+- Updated first-run `goal`/`ralph` workflow handoff guidance so new users see `/workflow status <id>` and `/workflow connect <id>` next steps with the run id, understand connect is where they can watch, attach, and steer, and know they can ask the current chat for status or steering at any point.
+- Removed the unused first-run onboarding scope-probe/routing-assessment subsystem and dead probe-only tests after normal-session prompt handoff became the active onboarding path.
 - Raised the bundled subagent and workflow-stage nesting budget to a hard maximum of five delegated levels, and documented the `0`-to-`5` recursion-guard range.
 
 ### Fixed
 
+- Fixed the first-run onboarding input placeholder so it uses muted TUI text and still renders a visible cursor while empty, making the startup composer read as an editable field instead of static copy.
+- Fixed `@` file-reference autocomplete in the first-run onboarding editor before the asynchronous `fd` readiness check completes by falling back to the built-in synchronous path completer while preserving `@` prefixes and quoted paths.
+- Fixed workflow config/discovery isolation so `ATOMIC_CODING_AGENT_DIR` prevents home-global workflows from shadowing the bundled first-run onboarding `goal` and `ralph` targets.
+- Fixed first-run onboarding returning-user detection so existing Atomic users with prior changelog state are marked onboarded and do not see the first-run CTA/placeholder when upgrading to a build that includes onboarding, while auth-only fresh installs and unfinished onboarding sessions still see the first-run flow.
+- Fixed first-run onboarding so multiline absolute path seeds with `:line[:column]` plus notes are saved or handed off with the full original text instead of being mistaken for slash commands.
+- Fixed successful `/import <jsonl>` during first-run onboarding so the imported session exits onboarding UI/interception state instead of treating the next normal message as a fresh onboarding seed.
+- Fixed first-run onboarding so a task saved before the session is ready resumes after successful `/model` selection, including the context-window follow-up step when required.
+- Fixed `/new` during first-run onboarding so the replacement session remains in onboarding but drops any previously saved in-memory task seed instead of resuming stale work later.
 - Fixed `find` and `search` glob entries in `paths`, restored `search.skip` file-page pagination for filesystem and resource-backed matches (including SQLite text primary keys with spaces), surfaced skip pagination hints across multiple pages when filesystem, archive, SQLite, internal, explicit-path, and ranged-selector search pages are full, avoided false continuation hints when later explicit targets do not match, kept `search` line-selector context inside the requested ranges for native and non-native fallback search, searched ranged single-file selectors without dropping matches beyond the internal raw grep cap while preserving backend regex semantics such as inline `(?i)`/`(?m)`/`(?x)`, normalized copied quoted/empty path inputs including `paths: []`, split delimiter-joined glob search/find/resource paths only after preserving exact filesystem paths with spaces or delimiter characters, awaited async internal-resource find resolvers and continued to fallback resolvers when earlier async resolvers returned `undefined`, resolved `local://`/router-backed find paths before filesystem normalization, preserved trailing slashes for directory find matches, stopped exact-file and exact-limit glob find hits from reporting false limit truncation while reporting real truncation when exact files fill the page before later targets, enforced custom find backend result limits without fabricating empty directory matches, made `find.timeout` return a partial timed-out result instead of accepting an ignored option, ensured custom find backends receive/enforce `hidden:false`, and ensured `gitignore:false` plus explicit `node_modules` globs include `node_modules` in native find/search scans ([#1483](https://github.com/bastani-inc/atomic/issues/1483)).
 - Fixed copied hashline output passed to `write` by stripping `[PATH#TAG]` headers, directory banners, continuation/truncation footers, and `LINE:` prefixes only for known current-session snapshots, including bounded/truncated read and search snippets, while preserving literal hashline-looking user content and rejecting unknown/stale tags from other snapshot stores; successful hashline edits now return compact refreshed-anchor metadata instead of the full post-edit file, `insert tail` now appends exactly once for trailing-newline, no-final-newline, and empty files, line-anchored edits on empty hashline snapshots no longer silently no-op, and multi-file hashline edits preflight all stale tags before writing any file ([#1483](https://github.com/bastani-inc/atomic/issues/1483)).
 - Fixed additional builtin parity gaps by removing the archive selector dependency on host `python3`, bounding oversized archive/internal/URL/SQLite/local-document reads like file reads while preserving oversized-read details for collapsed renderers, truncating resource-backed and SQLite search lines, aligning archive/internal/SQLite resource search regex semantics with filesystem search, avoiding inflation of unrelated zip members for selected reads/searches/writes, routing internal-resource selectors through a session router when available, preserving custom read/find backends that do not map to local files, filtering direct MCP tool allowlists that collide with the new builtin `search`, and expanding supported internal URLs in bash command/cwd/env inputs before execution ([#1483](https://github.com/bastani-inc/atomic/issues/1483)).
@@ -40,6 +52,7 @@
 - Addressed the latest PR review hardening pass by counting multi-file search per-file caps by match lines instead of context lines, making native filesystem scan cache insertion generation-aware so in-flight scans cannot repopulate after invalidation, rejecting SQLite raw-query `pragma_*` table-valued functions and double-quoted internal-name splices, and bounds-checking zip central-directory offsets during selective archive writes ([#1490](https://github.com/bastani-inc/atomic/pull/1490)).
 - Addressed the final PR review hardening pass by restoring header-only copied-hashline writes to their snapshot content instead of emptying files, decoding and sanitizing async bash output with a streaming UTF-8 decoder, cleaning up async bash temp output files on eviction/TTL, invalidating native search caches after bash commands, keeping URL protocol validation outside the private-read escape hatch, documenting single-file search skip handling, preserving CR-only hashline edit line endings, rejecting selective zip writes that would drop data descriptors, and exposing `search` in extension `tool_call`/`tool_result` type guards like other builtins ([#1490](https://github.com/bastani-inc/atomic/pull/1490)).
 
+
 ## [0.9.2] - 2026-06-23
 
 ### Changed

packages/coding-agent/docs/quickstart.md

@@ -80,6 +80,8 @@ See [Providers](/providers) for all supported providers, environment variables,
 
 ## First session
 
+On a fresh install with no prior Atomic startup state, Atomic starts with a first-run workflow prompt. Returning users with prior startup state are marked onboarded automatically and continue directly into the normal chat UI; stored credentials by themselves do not skip onboarding. Paste a ticket description, GitHub issue, path to a spec, or task prompt and Atomic hands it to the normal coding-agent session. The handoff raises the selected model to high reasoning when supported and first asks the parent agent to estimate scope from the seed text alone: tickets, issues, and especially specs often list enough work items, files, tests, docs, migrations, or acceptance criteria to classify likely size without immediately inspecting the repo. That text-only pass is treated as a routing confidence signal, not final planning. If the task is clearly tiny/small and high-confidence, the parent can route directly; if the seed references context that must be read or the scope is medium, large, unclear, or risky, it inspects only the necessary issue/spec/path/repo area and can use targeted read-only subagents such as `codebase-locator`, `codebase-analyzer`, and `codebase-pattern-finder` at their normal defaults. It then chooses `goal` for focused work or `ralph` for broader/riskier work, starts the selected workflow, and continues normally. If you paste the task before logging in or selecting a usable model, Atomic keeps only an in-memory copy, asks you to run `/login`, and resumes with the latest saved task after login or `/model` selection makes the session ready; `/new` starts a fresh unresolved onboarding session and drops that saved in-memory task. If you want normal chat instead, type `/chat` or `/chat <message>`; other slash commands such as `/login`, `/model`, and `/atomic` still work and do not dismiss onboarding.
+
 Once Atomic starts, the fastest way to get value is to kick off a built-in workflow or invoke a skill. Atomic turns repeatable engineering loops into executable stages with inspectable evidence instead of relying on a markdown checklist the model may or may not follow.
 
 For an interactive tour any time, run `/atomic` inside the TUI; `/atomic overview`, `/atomic workflows`, and `/atomic example` walk through the same flow in more depth.
@@ -92,7 +94,7 @@ Atomic ships with four workflows you can run immediately. Use `/workflow list` t
 |---|---|---|
 | `deep-research-codebase` | Broad, cross-cutting research before you decide what to change. Scout → research-history → parallel specialist waves → aggregator. | `/workflow deep-research-codebase prompt="How do payment retries work end to end?"` |
 | `goal` | Bounded one-off changes when you already know the work surface, exact outcome, and validation — for example tests, lint/typecheck, docs builds, or observable behavior. Keeps the run focused with a goal ledger, reviewer gates, final status `complete`, `blocked`, or `needs_human`, and optional final-stage PR creation with `create_pr=true` after approval. | `/workflow goal objective="Update the CLI docs for --json, include one example, run the docs build, and finish when the build passes"` |
-| `ralph` | Planned or broad implementation work from a spec file, GitHub issue, or crisp ticket description. Ralph refines the prompt, researches as needed, delegates implementation through sub-agents, reviews, records a QA proof video for UI/full-stack changes when practical, iterates, and optionally lets only the final stage attempt PR creation with `create_pr=true`. | `/workflow ralph prompt="Implement specs/2026-03-rate-limit.md and validate burst traffic returns 429"` |
+| `ralph` | Planned or broad implementation work from a spec file, GitHub issue, or crisp ticket description. Ralph researches as needed, delegates implementation through sub-agents, reviews, records a QA proof video for UI/full-stack changes when practical, iterates, and optionally lets only the final stage attempt PR creation with `create_pr=true`. | `/workflow ralph prompt="Implement specs/2026-03-rate-limit.md and validate burst traffic returns 429"` |
 | `open-claude-design` | UI and design-system work with separate forked generate and feedback chains; renders a live `preview.html` you can iterate against. | `/workflow open-claude-design prompt="Refresh the settings page hierarchy as a page"` |
 
 <p align="center"><img src="images/workflow-list.png" alt="Workflow List" width="600" /></p>
@@ -117,11 +119,12 @@ For smaller one-off tasks, use `goal` with a concrete task description that name
 
 ### Monitor and steer a run
 
-Named workflow runs execute in the background. After launch you get a run id; use it to inspect, attach, pause, or resume:
+Named workflow runs execute in the background. After launch you get a run id; use it to inspect, attach, pause, or resume. First-run `goal`/`ralph` handoffs show the exact `/workflow status <run-id>` and `/workflow connect <run-id>` commands in the dispatched card, and you can also ask in the current chat for status or to steer the run at any point.
 
 ```text
+/workflow status <run-id>         # inspect one run's progress
 /workflow status                  # list this session's active and terminal runs
-/workflow connect <run-id>        # open the graph viewer (F2 also opens the latest)
+/workflow connect <run-id>        # watch, attach to stages, or steer (F2 also opens latest)
 /workflow attach <run-id> <stage> # chat with one stage
 /workflow interrupt <run-id>      # pause resumably
 /workflow resume <run-id> "go"    # send a steer message and resume
@@ -213,7 +216,7 @@ Restart Atomic, or run `/reload`, after changing context files.
 
 ### Reference files
 
-Type `@` in the editor to fuzzy-search files, or pass files on the command line:
+Type `@` in any interactive editor, including first-run onboarding, to fuzzy-search files; or pass files on the command line:
 
 ```bash
 atomic @README.md "Summarize this"

packages/coding-agent/docs/settings.md

@@ -73,6 +73,8 @@ Use `/fast` in interactive mode to edit these settings. Atomic applies fast mode
 | `defaultProjectTrust` | string | `"ask"` | Fallback project trust behavior: `"ask"`, `"always"`, or `"never"`. Global setting only |
 | `collapseChangelog` | boolean | `false` | Show condensed changelog after updates |
 | `enableInstallTelemetry` | boolean | `true` | Send an anonymous install/update version ping after first install or changelog-detected updates. This does not control update checks |
+| `firstRunOnboardingStartedVersion` | string | - | Internal first-run onboarding start marker used when no prior Atomic startup state identifies the user as returning |
+| `onboardedVersion` | string | - | Internal one-time first-run onboarding completion marker. Returning-user detection from prior startup state, `/chat`, or a successful first-run seed handoff into the normal agent session sets it |
 | `doubleEscapeAction` | string | `"tree"` | Action for double-escape: `"tree"`, `"fork"`, or `"none"` |
 | `treeFilterMode` | string | `"default"` | Default filter for `/tree`: `"default"`, `"no-tools"`, `"user-only"`, `"labeled-only"`, `"all"` |
 | `editorPaddingX` | number | `0` | Horizontal padding for input editor (0-3) |

packages/coding-agent/docs/usage.md

@@ -19,7 +19,7 @@ The editor can be replaced temporarily by built-in UI such as `/settings` or by
 
 | Feature | How |
 |---------|-----|
-| File reference | Type `@` to fuzzy-search project files |
+| File reference | Type `@` to fuzzy-search project files, including during first-run onboarding |
 | Path completion | Press Tab to complete paths |
 | Multi-line input | SHIFT+Enter, or CTRL+Enter on Windows Terminal |
 | Images | Paste with CTRL+V, ALT+V on Windows, or drag into the terminal |