Docs: Comprehensive documentation out of sync with changelog features

[coygeek]

Subject: Docs: Comprehensive documentation out of sync with changelog features

Body:

Hi Claude Code team,

First off, fantastic work on the rapid pace of development for Claude Code. The tool is evolving quickly with powerful new features.

We've noticed that the official documentation is starting to lag significantly behind the features announced in the changelog. This makes it difficult for new and existing users to discover, understand, and properly utilize the full capabilities of the tool, often forcing us to rely on the changelog as a primary source of information.

To help bridge this gap, we've compiled a comprehensive list of discrepancies found between the changelog and the current documentation (scraped 2025-08-01).

Issue #1: Outdated and Directly Contradictory Information

This is the most critical category, as the documentation provides information that is actively incorrect.

• Deprecated claude config Commands: The settings.md page still documents and recommends using claude config set/get/list. However, v1.0.7 of the changelog marks these as deprecated in favor of editing settings.json directly.
• macOS Image Pasting: The common-workflows.md page explicitly warns users, "Do not use cmd+v" for pasting images. This is directly contradicted by v1.0.61, which added support for ⌘+V in VS Code on macOS.
• --append-system-prompt Behavior: The sdk.md documentation states this flag works "(only with --print)". This is outdated, as v1.0.51 enabled its use in interactive mode.

Issue #2: Major Undocumented Features

These are significant capabilities that are completely missing from the documentation.

• PDF Reading Support: v1.0.58 added support for reading PDFs, but this is not mentioned anywhere in the documentation.
• @agent Mention Syntax: v1.0.62 introduced the powerful @<agent-name> syntax to invoke subagents directly. The documentation only describes invoking agents via natural language.
• Missing Slash Commands: The built-in command list in slash-commands.md is missing:
  • /export (from v1.0.44) for exporting conversations.
  • /resume (from v1.0.27) for switching between conversations.
• Missing Keyboard Shortcuts: The interactive-mode.md page is missing critical shortcuts for:
  • Prompt input undo (Ctrl+U or Ctrl+_) from v1.0.33/v1.0.45.
  • Suspending the application (Ctrl+Z) and resuming (fg) from v1.0.44.

Issue #3: Missing Configuration Options & Flags

Numerous configuration options that provide greater control are not documented.

• Missing CLI Flags: The cli-reference.md file is missing:
  • --settings (v1.0.61): To load settings from a specific JSON file.
  • --system-prompt-file (v1.0.55): To override the system prompt from a file.
• Missing Environment Variables: The list in settings.md is missing:
  • CLAUDE_CODE_AUTO_CONNECT_IDE (v1.0.61)
  • CLAUDE_CODE_SHELL_PREFIX (v1.0.61)
  • CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR (v1.0.18)
• Subagent Model Customization: The sub-agents.md documentation is missing the model frontmatter field (added in v1.0.64) for specifying which model an agent should use.
• Slash Command argument-hint: The slash-commands.md documentation is missing the argument-hint frontmatter field (v1.0.54).

Issue #4: Incompletely Explained Features

Some features are mentioned in passing but are not properly explained.

• "Transcript Mode" (Ctrl+R): The changelog references this mode multiple times, but there is no central document explaining what it is, what it does, or its keybinding. The interactive-mode.md page (where it belongs) doesn't mention it.
• Redesigned Grep/Search Tool: v1.0.45 mentions a complete redesign of the Grep tool with "new tool input parameters and features." The documentation provides no details on these new parameters.
• XDG_CONFIG_HOME Support: Support for this standard Linux configuration directory (v1.0.28) is not mentioned.

Issue #5: Missing SDK and Advanced Tooling Features

• Missing SDK Features: The sdk.md page does not mention:
  • The canUseTool callback for programmatic tool confirmation (v1.0.59).
  • The ability to specify an env for the spawned SDK process (v1.0.59).
• Missing Hook Features: The hooks.md reference is missing:
  • The SessionStart event (v1.0.62) from the main list of hook events.
  • The systemMessage field (v1.0.64) from the advanced JSON output schema.

Bringing the documentation up to date with these features would be a huge help to the community and would improve the overall user experience significantly.

Thank you for your hard work on this amazing tool.

[richardkmichael]

Thank you for this!

CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR is exactly what I've been trying to prompt. 👍 I missed it in the changelog.

[coygeek]

PROGRESS UPDATE

FIXED / UPDATED

Based on the provided documentation, the Claude Code team has implemented fixes for several of the issues raised.

Implemented Fixes:

From Issue #2: Major Undocumented Features

• PDF Reading Support: The documentation now confirms that Claude Code can read PDFs.
  • Evidence: In en/docs/claude-code/sdk, the documentation states under the Python SDK section: "Supported formats: PNG, JPG, PDF, and other common formats". This corresponds to the feature added in changelog v1.0.58.

From Issue #3: Missing Configuration Options & Flags

• New Environment Variable Documented: One of the previously undocumented environment variables has been added.
  • Evidence: The environment variable table in en/docs/claude-code/settings now includes a definition for CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR, which was introduced in changelog v1.0.18.
• Slash Command argument-hint: The argument-hint frontmatter for custom slash commands is now documented.
  • Evidence: The "Frontmatter" table in en/docs/claude-code/slash-commands lists and describes the argument-hint field, which was added in changelog v1.0.54.

From Issue #5: Missing SDK and Advanced Tooling Features

• New Hook Event Documented: The SessionStart hook event is now included in the documentation.
  • Evidence: The hooks reference at en/docs/claude-code/hooks now lists SessionStart as an available hook event and provides its input schema. This corresponds to the feature from changelog v1.0.62.

The other issues raised in the ticket have not yet been addressed in the provided documentation.

---

NOT FIXED/UPDATED YET

Based on the documentation scraped on August 16, 2025, here is a detailed breakdown of the exact items from the GitHub ticket that have not yet been implemented by the developer team.

---

Issue #1: Outdated and Directly Contradictory Information

These items remain incorrect in the documentation.

• Deprecated claude config Commands: The documentation still actively promotes deprecated commands.

  • Evidence: The file en/docs/claude-code/settings has a section titled "Configuration options" that explicitly lists and recommends using claude config list, claude config get, claude config set, etc. This directly contradicts the changelog (v1.0.7) which states these are deprecated.

• macOS Image Pasting: The documentation provides a warning that is directly contradicted by a newer feature.

  • Evidence: In en/docs/claude-code/common-workflows, the "Work with images" section still warns users: "Copy an image and paste it into the CLI with ctrl+v (Do not use cmd+v)". This is outdated information, as changelog v1.0.61 added support for ⌘+V.

• --append-system-prompt Behavior: The flag's capability is still documented with an incorrect limitation.

  • Evidence: The CLI reference table in en/docs/claude-code/cli-reference describes the flag as: "Append to system prompt (only with --print)". This is incorrect, as changelog v1.0.51 enabled its use in interactive mode as well.

Issue #2: Major Undocumented Features

These significant features remain entirely missing from the documentation.

• @agent Mention Syntax: There is no mention of the @<agent-name> syntax for invoking subagents.

  • Evidence: The en/docs/claude-code/sub-agents file only describes invoking agents via natural language requests (e.g., "Use the code-reviewer subagent..."). The direct @ mention feature from changelog v1.0.62 is not documented.

• Missing Slash Commands: The primary list of built-in commands is incomplete.

  • Evidence: The command table in en/docs/claude-code/slash-commands is missing /export (from v1.0.44) and /resume (from v1.0.27).

• Missing Keyboard Shortcuts: Key shortcuts for undo and suspend are not documented.

  • Evidence: The tables in en/docs/claude-code/interactive-mode do not include entries for prompt input undo (Ctrl+U / Ctrl+_) or suspending the application (Ctrl+Z).

Issue #3: Missing Configuration Options & Flags

These configuration items are still not documented.

• Missing CLI Flags: The CLI reference is missing key flags.

  • Evidence: The table in en/docs/claude-code/cli-reference does not list the --settings flag (from v1.0.61) or the --system-prompt-file flag (from v1.0.55).

• Missing Environment Variables: The list of environment variables is incomplete.

  • Evidence: The table in en/docs/claude-code/settings is missing CLAUDE_CODE_AUTO_CONNECT_IDE and CLAUDE_CODE_SHELL_PREFIX, both from changelog v1.0.61.

• Subagent Model Customization: The ability to specify a model for a subagent is not documented.

  • Evidence: The "Configuration fields" table in en/docs/claude-code/sub-agents does not list the model frontmatter field, which was added in changelog v1.0.64.

Issue #4: Incompletely Explained Features

These features are either not explained or are only vaguely referenced.

• "Transcript Mode" (Ctrl+R): There is no explanation of this feature.

  • Evidence: While mentioned in the changelog and as a minor note in the hooks documentation, there is no section in en/docs/claude-code/interactive-mode or elsewhere that explains what "Transcript Mode" is, what it does, or that it is activated with Ctrl+R.

• Redesigned Grep/Search Tool: The new parameters and features are not detailed.

  • Evidence: The "Tools available to Claude" table in en/docs/claude-code/settings only provides a one-line description for Grep. It does not detail the new parameters or features from the redesign in changelog v1.0.45.

• XDG_CONFIG_HOME Support: Support for this Linux standard is not mentioned.

  • Evidence: A search of the documentation reveals no mention of XDG_CONFIG_HOME, so users would not know Claude Code respects this convention (added in v1.0.28).

Issue #5: Missing SDK and Advanced Tooling Features

These advanced features remain undocumented.

• Missing SDK Features: Key callbacks and options for the SDK are missing.

  • Evidence: The en/docs/claude-code/sdk documentation does not mention the canUseTool callback or the ability to specify an env for the spawned process, both added in changelog v1.0.59.

• Missing Hook Feature: An advanced JSON output field for hooks is not documented.

  • Evidence: The advanced JSON output schema in en/docs/claude-code/hooks is missing the systemMessage field, which was added in changelog v1.0.64.

[deksden]

1. 1.0.94: SDK: Add custom tools as callbacks - this is not documented

2. Sub-agents still DID NOT DOCUMENT MODEL settings - this is major feature! We have documentation in slash command, but not for sub-agent definition.

3. 1.0.93: NO_PROXY incorrectly documented in https://docs.anthropic.com/en/docs/claude-code/corporate-proxy as usupported feature. No examples, no other mentions.

4. 1.0.90: Settings file changes take effect immediately - no restart required. This is sightly incorrect definition - only setting itself are tracked, but slash commands / sub-agents definitions changes require restart. Maybe we need some clarification.

[github-actions]

This issue has been inactive for 30 days. If the issue is still occurring, please comment to let us know. Otherwise, this issue will be automatically closed in 30 days for housekeeping purposes.

[github-actions]

This issue has been automatically closed due to 60 days of inactivity. If you're still experiencing this issue, please open a new issue with updated information.

[github-actions]

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.