Problem Description

There are two related issues with the current --lambda-dir and --flatten flags that affect user experience:

1. Misleading --lambda-dir flag description

The current documentation states that --lambda-dir is the "Directory where the final lambda binaries will be located", but this is not actually true.

Current behavior:
When you run cargo lambda build --bin super-foobar --lambda-dir a/b/c, the actual result is:

a/b/c/super-foobar/bootstrap

What users expect based on the description:

a/b/c/bootstrap

The flag actually creates an additional subdirectory using the binary name within the specified path, which is not what the documentation suggests.

2. Redundant --flatten flag requirement

To get the expected behavior (binary directly in the specified directory), users must use the --flatten flag and repeat the binary name:

cargo lambda build --bin super-foobar --lambda-dir a/b/c --flatten super-foobar

This is redundant because:

• The binary name is already specified with --bin super-foobar
• Users have to repeat "super-foobar" in both --bin and --flatten
• It's not intuitive that you need an additional flag to get the behavior described in the documentation

Proposed Solutions

Option 1: Fix the documentation

Update the --lambda-dir flag description to accurately reflect its current behavior:

Current description:

Directory where the final lambda binaries will be located

Proposed description:

Base directory where lambda binaries will be located. Each binary will be placed in a subdirectory named after the binary (e.g., --lambda-dir target/lambda with --bin foo creates target/lambda/foo/bootstrap)

Option 2: Improve --flatten ergonomics

Make the --flatten flag more user-friendly by:

1. Auto-detect binary name: When only one binary is being built, --flatten could automatically use that binary name without requiring it to be specified again
2. Add a boolean --flatten option: --flatten without a value could automatically flatten the currently selected binary

Examples:

# Current (redundant)
cargo lambda build --bin super-foobar --lambda-dir a/b/c --flatten super-foobar

# Proposed (auto-detect when building single binary)
cargo lambda build --bin super-foobar --lambda-dir a/b/c --flatten

# Or even shorter with boolean flag
cargo lambda build --bin super-foobar --lambda-dir a/b/c --flatten

Option 3: Combined approach

1. Fix the documentation to be accurate
2. Improve --flatten ergonomics for better user experience
3. Consider adding a --direct or similar flag as an alias for the common use case

Impact

This issue affects user experience by:

1. Confusing documentation - Users expect different behavior than what actually happens
2. Verbose commands - Users have to repeat information unnecessarily
3. Discoverability - The --flatten flag behavior is not obvious to new users

Improving this would make cargo-lambda more intuitive and user-friendly, especially for newcomers who expect the directory structure to match the documentation.