docs(cli): update --fullsend-dir help text from stale layout phrasing

[waynesun09]

Summary

• Update --fullsend-dir help text across all 7 CLI commands from "base directory containing the .fullsend layout" to "path to the .fullsend configuration directory"
• Update eval script comment from "fullsend scaffold directory" to match
• Update CLI reference docs (docs/cli/agent.md, docs/guides/dev/cli-internals.md, docs/testing/functional-tests.md)

Context

Issue #5288 flagged the stale .fullsend layout phrasing in the --fullsend-dir help text. After investigation, the flag name itself is correct — the directory IS the .fullsend/ project configuration root (config, harness, lock, profiles, providers). The "layout" phrasing was a holdover from the pre-agent-extraction era when the directory mirrored the internal/scaffold/ structure.

This PR keeps the --fullsend-dir flag name and only updates the description to reflect what the directory actually contains. Supersedes #5291 which attempted a full flag rename.

Refs: #5288

Testing

• go vet ./internal/cli/... passes
• gofmt clean
• No functional changes — help text only

[qodo-code-review]

PR Summary by Qodo

Docs: clarify --fullsend-dir as the .fullsend configuration directory

📝 Documentation ✨ Enhancement 🕐 10-20 Minutes

AI Description

• Clarify --fullsend-dir help text across CLI commands to match current .fullsend/ semantics
• Align eval script and functional test docs with the updated .fullsend directory description
• Keep flag name stable (no behavior change), updating only user-facing wording

Diagram

graph TD
  U([Developer]) --> CLI["fullsend CLI (cobra)"] --> OUT(["Help/usage output"]
  CLI --> FLAG["--fullsend-dir description"]
  DOCS[/"CLI & guide docs"/] --> FLAG
  EVAL["run-fullsend.sh"] --> ENV["FULLSEND_DIR meaning"] --> FLAG

  subgraph Legend
    direction LR
    _actor(["User"]) ~~~ _comp["Component"] ~~~ _doc[/"Docs"/]
  end

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Rename the flag (e.g., --config-dir / --dotfullsend-dir)

• ➕ Terminology would be self-describing without relying on help text
• ➕ Avoids any lingering confusion around what “fullsend dir” means
• ➖ Breaking CLI change; requires deprecation strategy and migration docs
• ➖ Touches more call sites, scripts, and user automation than needed for Deprecate --fullsend-dir in favor of a clearer name (e.g. --agent-dir) #5288

2. Centralize the help string in a shared constant

• ➕ Prevents future drift across multiple commands
• ➕ Makes wording updates a single-line change
• ➖ Small refactor across command files; slightly larger diff
• ➖ Not strictly necessary for a one-time wording fix

Recommendation: The PR’s approach (keep the flag name, update only the description everywhere it appears) is the best low-risk fix for #5288 and avoids a breaking rename. If this wording is expected to evolve again, a follow-up refactor to centralize the help string would reduce repetition across commands.

Files changed (8) +17 / -17

Documentation (8) +17 / -17

agent.mdUpdate --fullsend-dir wording in agent command reference +5/-5

Update --fullsend-dir wording in agent command reference

• Replaces the stale “base directory containing the .fullsend layout” phrasing with “path to the .fullsend configuration directory” across the documented agent subcommands.

docs/cli/agent.md

cli-internals.mdAlign CLI internals tree comments for --fullsend-dir +3/-3

Align CLI internals tree comments for --fullsend-dir

• Updates the inline CLI tree annotations so '--fullsend-dir' is described as the '.fullsend' configuration directory for migrate/lock/run sections.

docs/guides/dev/cli-internals.md

functional-tests.mdClarify FULLSEND_DIR meaning in functional test env table +1/-1

Clarify FULLSEND_DIR meaning in functional test env table

• Updates the FULLSEND_DIR description to reflect that it points at the '.fullsend' configuration directory (defaulting to internal scaffold).

docs/testing/functional-tests.md

run-fullsend.shUpdate FULLSEND_DIR comment to match .fullsend terminology +1/-1

Update FULLSEND_DIR comment to match .fullsend terminology

• Adjusts the required environment variable comment to describe FULLSEND_DIR as the '.fullsend' configuration directory; no script behavior changes.

eval/scripts/run-fullsend.sh

agent.goUpdate --fullsend-dir help text for agent subcommands +4/-4

Update --fullsend-dir help text for agent subcommands

• Changes the Cobra flag description string for '--fullsend-dir' on agent add/list/update/remove to reference the '.fullsend' configuration directory instead of a “layout”.

internal/cli/agent.go

lock.goUpdate --fullsend-dir help text for lock command +1/-1

Update --fullsend-dir help text for lock command

• Adjusts the '--fullsend-dir' flag help string to the new '.fullsend' configuration directory wording.

internal/cli/lock.go

migrate.goUpdate --fullsend-dir help text for migrate-customizations +1/-1

Update --fullsend-dir help text for migrate-customizations

• Updates the '--fullsend-dir' flag description to the '.fullsend' configuration directory wording for migration flows.

internal/cli/migrate.go

run.goUpdate --fullsend-dir help text for run command +1/-1

Update --fullsend-dir help text for run command

• Updates the run command’s '--fullsend-dir' help description to match the '.fullsend' configuration directory terminology.

internal/cli/run.go

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 10:07 PM UTC · Completed 10:19 PM UTC
Commit: 694e31b · View workflow run →

[github-actions]

Site preview

Preview: https://6df09b71-site.fullsend-ai.workers.dev

Commit: 694e31bf4af1c8f3a8086054dca50ec483c0c72a

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📜 Skill insights (1)

Context used

✅ Compliance rules (platform): 54 rules

✅ Skills: writing-user-docs, writing-adrs

1. Guide under docs/guides/dev/ 📜 Skill insight ⌂ Architecture

Description

A modified guide file is located under docs/guides/dev/, but guides must live under either
docs/guides/admin/ or docs/guides/user/. This breaks the required documentation directory
structure and can cause the guide index and audience targeting rules to be applied inconsistently.

Code

docs/guides/dev/cli-internals.md[R105-117]

+│       ├── --fullsend-dir <dir>             #   .fullsend configuration directory
│       ├── --repo <owner/repo>              #   Target repo for migration PR
│       └── --dry-run                        #   Preview changes without PR
├── lock             [agent-name]              # Pin remote deps to lock.yaml
│   ├── --all                                #   Lock all harnesses in the harness directory
-│   ├── --fullsend-dir <path>                #   Base directory with .fullsend layout
+│   ├── --fullsend-dir <path>                #   .fullsend configuration directory
│   ├── --forge <platform>                   #   Lock only this forge variant; omit for all
│   ├── --update                             #   Force re-resolve even if current
│   ├── --offline                            #   Reject network fetches
│   ├── --max-depth <int>                    #   Max transitive dependency depth
│   └── --max-resources <int>                #   Max total remote resources
├── run                                      # Execute an agent in a sandbox
-│   ├── --fullsend-dir <path>                #   Base directory with .fullsend layout
+│   ├── --fullsend-dir <path>                #   .fullsend configuration directory

Relevance

⭐ Low

Similar “move docs/guides/dev to user/admin” suggestion was rejected in PR #4901; dev guides are
maintained in-tree.

PR-#4901
PR-#1087

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

PR Compliance ID 1062077 requires every guide under docs/guides/ to be placed in either admin/
or user/. The modified file is under docs/guides/dev/, which violates the directory requirement.

docs/guides/dev/cli-internals.md[105-117]
Skill: writing-user-docs

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`docs/guides/dev/cli-internals.md` was modified in this PR, but the compliance rule requires that all guide files under `docs/guides/` be placed in either `admin/` or `user/`.

## Issue Context
The PR updated content in `docs/guides/dev/cli-internals.md`, keeping the file under an unsupported `dev/` subdirectory.

## Fix Focus Areas
- docs/guides/dev/cli-internals.md[105-117]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[fullsend-ai-review]

Review

Findings

Low

• [stale-terminology] eval/run-functional.sh:13 — Comment still uses old "fullsend scaffold directory" phrasing. The PR updates this same term to ".fullsend configuration directory" in eval/scripts/run-fullsend.sh and docs/testing/functional-tests.md but missed this occurrence.
  Remediation: Update line 13 to match the new phrasing.

---

Labels: PR updates CLI help text and documentation for --fullsend-dir flag

[fullsend-ai-retro]

🤖 Finished Retro · ✅ Success · Started 8:20 PM UTC · Completed 8:30 PM UTC
Commit: 694e31b · View workflow run →

[fullsend-ai-retro]

PR #5424 workflow went well. This was a clean, human-authored docs/help-text fix updating --fullsend-dir descriptions from stale "base directory containing the .fullsend layout" to "path to the .fullsend configuration directory" across 8 files. It superseded the agent-generated PR #5291, which attempted a full flag rename (--fullsend-dir → --agent-dir) based on a flawed premise — the .fullsend/ directory is a project configuration root, not just agent definitions.

Review agent performed effectively. The review agent (claude-opus-4-6, ~13 min) approved the PR but correctly identified a missed occurrence: eval/run-functional.sh:13 still uses "fullsend scaffold directory" phrasing while the PR updated the same description in eval/scripts/run-fullsend.sh and docs/testing/functional-tests.md. This is a genuine cross-file consistency catch on a file outside the diff. The human reviewer (rh-hemartin) approved without inline comments ~34 hours later. The PR merged cleanly via merge queue.

One valid finding was not addressed. The review agent's Low finding about eval/run-functional.sh:13 was not fixed before merge. The stale phrasing remains in the codebase. One proposal is filed below to track this.

Evidence for existing open issues:

• fullsend-ai/agents#348: The triage validation gap that led to the wasted PR feat(cli)!: rename --fullsend-dir to --agent-dir with deprecation alias #5291 is already tracked. PR docs(cli): update --fullsend-dir help text from stale layout phrasing #5424 is the corrective outcome.
• fullsend-ai/fullsend#5289: This PR provides additional autonomy-readiness evidence — the review agent exceeded human review by catching a valid missed occurrence that neither the PR author nor human reviewer flagged.
• fullsend-ai/fullsend#1794: The missed eval/run-functional.sh occurrence is the type of miss that grep-verify after terminology updates would catch.
• fullsend-ai/agents#373: The review took ~13 minutes for a 17-line docs-only change, consistent with the hypothesis that skipping irrelevant review dimensions for trivial docs PRs could reduce cost.

Proposals filed

• Fix stale FULLSEND_DIR description in eval/run-functional.sh missed by PR #5424 (in fullsend-ai/fullsend)