Choose a Documentation Audience

Every new or substantially revised document must identify its reader and publication target before content is written.

Review questions

1. Is the reader an end user, an agent/operator, or a contributor/maintainer? 2. Is the page a tutorial, how-to, reference, or explanation? 3. Should it appear on `docs.aiwg.io`, in the installed/release agent corpus, or only in contributor/development surfaces? 4. Does a public command genuinely require direct user action? 5. If an agent owns the command, does the public page instead state the user ask, expected agent behavior, approval boundary, outcome, and verification?

Agent/operator references belong in `docs/agents/` with the metadata and stable ID defined in the documentation information architecture. Public exceptions must use a direct-touch command from the documented allowlist or label the command as an operator/recovery escape hatch.

Do not mechanically rewrite historical release notes or example fixtures.

Clarity for new computer users

Public docs must not assume that readers know what a terminal, project root, provider, repository, command flag, generated file, or restart/reload means. Define unfamiliar terms where the user first needs them. For every required action, state:

• where it happens (terminal, file browser, or agent conversation);
• what the action changes and why;
• whether approval is expected;
• what success looks like; and
• how to stop or recover safely when the result differs.

Use respectful adult language. Avoid both unexplained shorthand and patronizing reassurance.