Documentation

Plain-language style

These rules make the documentation readable for a wide audience. Plain language helps accessibility, and it keeps technical detail. A sentence can be plain and still precise. Humans and autonomous agents both read these docs, and short, unambiguous sentences serve both.

New content must follow these rules. When you edit existing prose, you decide how far to apply them. Rewriting whole paragraphs to match can make a review harder, so the person making the change judges what to rewrite.

Each rule comes with a NO/YES example pair.

Active voice

Write in plain language. Use the active voice and say who does what.

• NO: Resources are deleted by fullsend when the label is removed.
• YES: Fullsend deletes resources when you remove the label.

Short sentences

Keep sentences short. Put one idea in each sentence.

• NO: The agent reads the issue, which triage has already labeled, and then opens a pull request after the tests pass.
• YES: The agent reads the labeled issue. It runs the tests. When they pass, it opens a pull request.

Plain words

Use plain words, such as "use" instead of "utilize".

• NO: Utilize the --dry-run flag to facilitate validation of the configuration.
• YES: Use the --dry-run flag to check the configuration.

Noun clusters

Expand long noun clusters into a phrase.

• NO: Set the agent sandbox network egress policy file path.
• YES: Set the path to the file that controls which hosts the agent sandbox can reach.

Terms and idioms

Define a term on first use. Use literal wording instead of idioms.

• NO: The mint is a one-stop shop for tokens.
• YES: The mint, the service that issues short-lived forge tokens, provides every token an agent needs.

Present tense

Use present tense, not future or past.

• NO: When configured in this way fullsend will delete resources.
• YES: When configured in this way fullsend deletes resources.

Second and third person

Use the second person to address the reader and the third person to describe things. Avoid the first person.

• NO: We create the following configuration file.
• YES: Create the following configuration file.

Positive phrases

Use positive phrases. Negative phrases can confuse readers, and two negatives in one sentence confuse them most.

• NO: If the label is not present, the agent does not run.
• YES: The agent runs only when the label is present.

Cautious claims

Use cautious language for performance, benefits, best practices, and security.

• NO: Caching improves the speed of agent runs.
• YES: Caching can improve the speed of agent runs.

Recommendations

State what to do instead of saying that it is recommended.

• NO: It is recommended that you pin actions to a commit SHA.
• YES: Pin actions to a commit SHA.

Abbreviations

Use English abbreviations, not Latin ones.

• NO: Set a forge token, e.g. a GitHub App token.
• YES: Set a forge token, for example a GitHub App token.

Keeping references in sync

When adding, removing, renaming, or changing the behavior of CLI commands, flags, configuration variables, or environment variables, you must update every documentation file that references the affected feature. CLI commands are documented across CLI reference pages, user and operator guides, ADRs, and inline Go help text. Missing even one location causes documentation drift that surfaces as review findings on later PRs.

General discovery rule

Before considering a CLI, configuration, or environment-variable change complete, search for the affected command or setting:

grep -rn '<command-or-setting-name>' docs/ internal/ .github/

The internal/cli/ path covers inline Short/Long help text in Go source, and internal/config/ defines config.yaml fields. Review every hit and update references that describe behavior you changed. For new commands or settings with no literal match, also inspect tables and lists of comparable commands, flags, or variables. This catches files not listed in the cross-reference below.

Configuration and environment variables

For a .fullsend/config.yaml field, update docs/reference/config-reference.md, the canonical reference for every field. If its layered resolution or defaults change, also check docs/guides/infrastructure/layered-config-reference.md. For an environment variable or repository variable, check the repository-variable table in docs/guides/getting-started/operations.md and the documentation for the feature that consumes it.

Planning artifacts from agent sessions

Do not commit spec, plan, task, or research files that a local agent session generates. This includes specs/ directories and other output in the style of spec-kit or OpenSpec, such as spec.md, plan.md, tasks.md, and research.md. Remove them from your branch before you open a pull request. Reviewers should ask for their removal when they appear in a PR.

These files describe how one session approached a change. They are not maintained after the change lands, so they go stale and mislead later readers. The same policy removed docs/plans/ and docs/superpowers/ from the repository in PR #5972, and both paths are listed in .gitignore.

Record the durable outcome in the right place instead:

• Design decisions belong in an ADR (see ADR conventions).
• Implementation detail belongs in code, code comments, and tests.

ADR annotations

When a CLI change makes an ADR's decision obsolete, write a new ADR that supersedes the old one rather than editing the original decision text. Minor annotations (status updates, "see also" links) are welcome — see ADR conventions for the full rules.

Heading anchors

Heading anchors on the docs site follow GitHub's slug rules (for example ## 4. Next step is #4-next-step), so a link that lychee (make lint-md-links) accepts also works on the site.

Product name casing

Write the product name as lowercase "fullsend" in running prose. Capitalize it as "Fullsend" only at the start of a sentence and in titles and headings. Leave code, inline code, URLs, file paths, identifiers, and quoted text as they are.

Line wrapping

Wrap prose in Markdown files at about 80 columns. Git and GitHub compare Markdown line by line. When a paragraph sits on one long line, editing a single word marks the whole paragraph as changed, and reviewers have to hunt for the real edit. When lines are wrapped, a small wording fix changes only the lines it touches.

• Break lines at word boundaries, close to 80 columns. The limit is a guide, not an exact count, and no linter enforces it, so reviewers check it.
• Indent the continuation lines of a list item to line up with the item's text, so they stay part of the item.
• Wrapping does not change the rendered page. Markdown joins consecutive lines of a paragraph into one.

Leave these as they are, because wrapping them breaks rendering or meaning:

• Table rows. Each row must stay on one line.
• Fenced code blocks. Keep their content exactly as it should be copied or run.
• Headings.
• Long URLs and link targets that do not fit within the limit by themselves.

Do not rewrap existing documents wholesale. That produces the same large diffs this rule is meant to prevent. Write new content wrapped, and rewrap an existing paragraph only when you are already editing it.

CLI reference pages are manually maintained

CLI reference pages under docs/cli/ are manually maintained and will not auto-update. When modifying CLI commands, flag help text, defaults, or behavior in internal/cli/, update the corresponding reference page in docs/cli/ as well as relevant tables and descriptions in docs/guides/.

Adding new documentation pages

When adding a new doc under docs/, check docs/.vitepress/config.ts sidebar configuration. Sections using getMarkdownFiles() are auto-discovered, including nested directories (which become nested sidebar groups). All other sections require a manual { text, link } entry. Also add the new folder's prefix to search.options.scopes in the same file so the folder's pages are reachable when search scope pills are active.

Cross-reference by command group

Each row lists the documentation touchpoints for a major CLI command group. The Go source column is where inline Short/Long help text lives.

agent

Category	Files
CLI reference	docs/cli/agent.md
Guides	docs/guides/getting-started/operations.md, docs/guides/user/bring-your-own-agent.md, docs/guides/user/customizing-agents.md, docs/guides/user/customizing-with-skills.md, docs/guides/dev/cli-internals.md
ADRs	docs/ADRs/0058-agent-registration.md
Go source	internal/cli/agent.go

admin foreign

The admin command group's uninstall/analyze/enable/disable subcommands were removed with per-org installation (ADR-0044); admin install is deprecated but still works as repository-only (<owner/repo>) installation (it still creates every role's GitHub App in one run). The other actively supported subcommand is admin foreign (cross-org mint-authorization allow-list).

Category	Files
CLI reference	(no dedicated page)
Guides	docs/guides/infrastructure/mint-administration.md, docs/guides/dev/cli-internals.md, docs/guides/dev/e2e-testing.md
ADRs	docs/ADRs/0060-cross-org-mint-authorization-via-org-variables.md, docs/ADRs/0083-repo-level-foreign-allow-list.md
Go source	internal/cli/admin.go

github

Category	Files
CLI reference	docs/cli/github.md
Guides	docs/guides/getting-started/configuring-github.md, docs/guides/getting-started/migrating-from-github-setup.md, docs/guides/getting-started/operations.md, docs/guides/dev/cli-internals.md, docs/guides/dev/e2e-testing.md
ADRs	docs/ADRs/0057-repos-management.md
Go source	internal/cli/github.go

inference

Category	Files
CLI reference	docs/cli/inference.md
Guides	docs/guides/getting-started/getting-inference.md, docs/guides/user/inference-gateway.md, docs/guides/getting-started/operations.md, docs/guides/dev/cli-internals.md
Go source	internal/cli/inference.go

mint

Category	Files
CLI reference	docs/cli/mint.md
Guides	docs/guides/getting-started/operations.md, docs/guides/infrastructure/mint-administration.md, docs/guides/infrastructure/infrastructure-reference.md, docs/guides/infrastructure/advanced-setup.md, docs/guides/infrastructure/standalone-mint.md, docs/guides/dev/cli-internals.md
ADRs	docs/ADRs/0059-public-mint-mode-with-wildcard-allowlists.md, docs/ADRs/0060-cross-org-mint-authorization-via-org-variables.md, docs/ADRs/0073-named-mint-privilege-levels.md, docs/ADRs/0077-mint-repos-scope-hardening.md, docs/ADRs/0078-simplified-mint-authorization-policy.md, docs/ADRs/0082-workflow-host-allow-list.md
Go source	internal/cli/mint.go, internal/cli/mint_setup.go, internal/cli/mint_delete.go, internal/cli/minttoken.go

repos

Category	Files
CLI reference	docs/cli/repos.md
Guides	docs/guides/getting-started/operations.md, docs/guides/getting-started/repo-management.md, docs/guides/getting-started/getting-inference.md, docs/guides/getting-started/configuring-gitlab.md, docs/guides/getting-started/migrating-from-github-setup.md, docs/guides/dev/cli-internals.md, docs/guides/infrastructure/layered-config-reference.md
ADRs	docs/ADRs/0057-repos-management.md, docs/ADRs/0074-repos-command-consolidation.md, docs/ADRs/0122-declarative-repo-configuration.md
Go source	internal/cli/repos.go, internal/cli/repos_gitlab.go, internal/cli/repos_gitlab_service_accounts.go

run

Category	Files
CLI reference	docs/cli/run.md
Guides	docs/guides/user/running-agents-locally.md, docs/guides/user/bring-your-own-agent.md, docs/guides/dev/cli-internals.md
ADRs	docs/ADRs/0036-agent-execution-sandbox.md, docs/ADRs/0136-runner-secrets-through-one-stored-secret.md
Contributing	docs/contributing/sandbox-topology.md
Go source	internal/cli/run.go

issues

Category	Files
CLI reference	(no dedicated page)
Guides	docs/guides/user/issues-commands.md, docs/guides/user/jira-integration.md, docs/guides/infrastructure/layered-config-reference.md, docs/guides/dev/cli-internals.md
Go source	internal/cli/issues.go

Minor commands

Commands without a subsection above have lighter documentation footprints. Apply the general grep rule when changing them. The comprehensive single reference for all commands (including minor ones) is docs/guides/dev/cli-internals.md, which documents the full command tree with flags.