Add second-pass chat UX milestones

Extend the chat-ergonomics roadmap with the remaining UX work highlighted by the readiness review.

Document a second pass focused on removing shell glue from canonical CLI handoff flows, making the recommended chat-host profile more obvious without changing 3.x compatibility defaults, and polishing human-mode content reads for cleaner transcripts and copy-paste behavior.

Keep these milestones explicitly workspace-first and scoped to product UX, with CLI-only shortcuts allowed where the SDK and MCP surfaces already provide the structured behavior natively.

docs/roadmap/llm-chat-ergonomics/3.7.0-handoff-shortcuts-and-file-input-sources.md

@@ -0,0 +1,48 @@
+# `3.7.0` Handoff Shortcuts And File Input Sources
+
+Status: Planned
+
+## Goal
+
+Remove the last bits of shell plumbing from the canonical CLI workspace flows so
+they feel productized instead of hand-assembled.
+
+## Public API Changes
+
+Planned additions:
+
+- `pyro workspace create ... --id-only`
+- `pyro workspace shell open ... --id-only`
+- `pyro workspace file write WORKSPACE_ID PATH --text-file PATH`
+- `pyro workspace patch apply WORKSPACE_ID --patch-file PATH`
+
+## Implementation Boundaries
+
+- keep existing `--json`, `--text`, and `--patch` stable
+- treat these additions as CLI-only shortcuts over already-structured behavior
+- make `--text` and `--text-file` mutually exclusive
+- make `--patch` and `--patch-file` mutually exclusive
+- read file-backed text and patch inputs as UTF-8 text
+- keep `/workspace` scoping and current patch semantics unchanged
+
+## Non-Goals
+
+- no new binary file-write story
+- no new SDK or MCP surface just to mirror CLI shorthand flags
+- no hidden patch normalization beyond the current patch-apply rules
+- no change to the stable `workspace_id` contract
+
+## Acceptance Scenarios
+
+- README, install docs, and first-run docs can create one workspace ID without
+  `python -c` output parsing
+- a user can apply a patch from `fix.patch` without `$(cat fix.patch)` shell
+  expansion
+- a user can write one text file from a host file directly, without
+  shell-escaped inline text
+
+## Required Repo Updates
+
+- top-level workspace walkthroughs rewritten around the new shortcut flags
+- CLI help text updated so the shortest happy path is copy-paste friendly
+- at least one smoke scenario updated to use a file-backed patch input

docs/roadmap/llm-chat-ergonomics/3.8.0-chat-host-onramp-and-recommended-defaults.md

@@ -0,0 +1,51 @@
+# `3.8.0` Chat-Host Onramp And Recommended Defaults
+
+Status: Planned
+
+## Goal
+
+Make the recommended chat-host entrypoint obvious before a new integrator has
+to read deep integration docs.
+
+## Public API Changes
+
+No breaking API change is required in this milestone.
+
+The main user-visible change is guidance:
+
+- `pyro mcp serve` help text should clearly call `workspace-core` the
+  recommended chat-host profile
+- README, install docs, first-run docs, and shipped MCP configs should all lead
+  with `workspace-core`
+- `workspace-full` should be framed as the explicit advanced/compatibility
+  surface for `3.x`
+
+## Implementation Boundaries
+
+- keep the `3.x` compatibility default unchanged
+- do not add new profile names
+- make the recommendation visible from help text and top-level docs, not only
+  the integrations page
+- keep provider examples and MCP examples aligned on the same profile story
+
+## Non-Goals
+
+- no breaking default flip to `workspace-core` in `3.x`
+- no new hidden server behavior based on client type
+- no divergence between CLI, SDK, and MCP terminology for the profile ladder
+
+## Acceptance Scenarios
+
+- a new chat-host integrator sees `workspace-core` as the recommended first MCP
+  profile from the first help/doc pass
+- the top-level docs include one tiny chat-host quickstart near the first-run
+  path
+- shipped config examples and provider examples all align on the same profile
+  progression
+
+## Required Repo Updates
+
+- top-level docs updated with a minimal chat-host quickstart
+- `pyro mcp serve --help` rewritten to emphasize `workspace-core`
+- examples and config snippets audited so they all agree on the recommended
+  profile

docs/roadmap/llm-chat-ergonomics/3.9.0-content-only-reads-and-human-output-polish.md

@@ -0,0 +1,50 @@
+# `3.9.0` Content-Only Reads And Human Output Polish
+
+Status: Planned
+
+## Goal
+
+Make human-mode content reads cleaner for chat logs, terminal transcripts, and
+copy-paste workflows.
+
+## Public API Changes
+
+Planned additions:
+
+- `pyro workspace file read WORKSPACE_ID PATH --content-only`
+- `pyro workspace disk read WORKSPACE_ID PATH --content-only`
+
+Behavioral polish:
+
+- default human-mode `workspace file read` and `workspace disk read` should
+  always separate content from summaries cleanly, even when the file lacks a
+  trailing newline
+
+## Implementation Boundaries
+
+- keep JSON output unchanged
+- keep human-readable summary lines by default
+- `--content-only` should print only the file content and no summary footer
+- keep current regular-file-only constraints for live and stopped-disk reads
+
+## Non-Goals
+
+- no new binary dumping contract
+- no removal of human summaries from the default read path
+- no expansion into a generic pager or TUI reader
+- no change to SDK or MCP structured read results, which are already summary-free
+
+## Acceptance Scenarios
+
+- reading a text file with no trailing newline still produces a clean transcript
+- a user can explicitly request content-only output for copy-paste or shell
+  piping
+- docs can show both summary mode and content-only mode without caveats about
+  messy output joining
+
+## Required Repo Updates
+
+- CLI help text updated for file and disk read commands
+- stable docs and transcripts revised to use `--content-only` where it improves
+  readability
+- tests that cover missing trailing newline cases in human mode