docs(workspaces): document asynchronous workspace naming

SI
2mo ago
+21-1

What & why

#7518 moved workspace naming off the workspace-creation and agent-startup paths. The Workspaces page only said names are generated from the prompt; it didn't describe placeholders, retries, branch-rename conditions, or restart behavior.

This adds an "Automatic Naming" section to apps/docs/content/docs/workspaces.mdx:

  • Placeholder names (New workspace, local for Local checkouts, New session), and that PR and existing-worktree workspaces aren't renamed.
  • What naming uses (prompt, linked issue/PR, agent reply), retries, and the failure warning.
  • When Superset renames an automatic branch, and that manual title and branch edits take precedence.
  • That pending naming is lost if the host service restarts, while files, terminals, and running agents are unaffected.

Docs only. Relates to #7518 (reference commit 3fe2c3636e303ecd3a62d4e63bfaba4428bfbdaf).

How I tested it

  • bun run lint: passed
  • bun run typecheck in apps/docs (includes fumadocs-mdx): passed
  • git diff --check: passed
  • Checked each claim against the naming implementation at the reference commit (workspace-naming-job.ts, workspace-naming-state.ts, workspace-title-jobs.ts, ai-workspace-names.ts, workspaces.ts, create-session.ts)

Checklist

  • PR title follows conventional commits (type(scope): subject)
  • bun run lint and bun run typecheck pass (CI fails on lint warnings too) — typecheck run for apps/docs, the only package touched
  • "Allow edits from maintainers" is checked on fork PRs

🤖 Generated with Claude Code


Summary by cubic

Documents asynchronous workspace naming in the Workspaces docs page.

Adds an "Automatic Naming" section covering:

  • Placeholder names (New workspace, local, New session) and that PR and existing-worktree workspaces aren't renamed.
  • What naming uses (prompt, linked issue/PR, agent reply), retries, and the failure warning.
  • When Superset renames an automatic branch, and that manual title and branch edits take precedence.
  • That pending naming is lost if the host service restarts, while files, terminals, and running agents are unaffected.

Docs only.

Summary by CodeRabbit

  • Documentation
    • Expanded the workspace guide with details about automatically generated names, including placeholder names, generation retries, and warnings.
    • Clarified when branch names change, how user-provided name overrides are handled, and what happens to pending name generation after a host-service restart.