# Manual page specification

[`PRODUCT.md`](PRODUCT.md) incorporates this document as normative version 1 behavior.
The manual page describes released behavior; it does not define behavior independently.

## Artifact

The repository contains a hand-authored `man/termux-janitor.1` source in portable `man(7)` roff.
It requires no documentation generator or third-party build dependency.

Installation places it at `$PREFIX/share/man/man1/termux-janitor.1` or the packaging system's
compressed form of that file. `man termux-janitor` must find it after a normal package installation.

The title is `TERMUX-JANITOR(1)`. The displayed release version comes from the same version value as
`termux-janitor --version`. Build and packaging steps must not insert the wall clock into the
output. When a date is required, they derive it from release metadata or `SOURCE_DATE_EPOCH`.

## Required content

The page contains these sections in this order:

1. `NAME`, containing one concise purpose sentence;
2. `SYNOPSIS`, covering every invocation accepted by [`PRODUCT.md` section 13](PRODUCT.md#13-cli-surface);
3. `DESCRIPTION`, explaining scan, review, exact confirmation, execution, and reconciliation;
4. `SAFETY`, stating the confirmation, manual-only, revalidation, symlink, package-owner, privilege,
   incomplete-result, and audit-log guarantees;
5. `OPTIONS`, documenting every option and every usage conflict;
6. `INTERACTION`, summarizing the key map and pointing to contextual `?` help;
7. `CONFIGURATION`, naming precedence, strict validation, and the effective-file display;
8. `FILES`, listing configuration and state locations without assuming unset XDG variables;
9. `NETWORK`, describing local-first operation, disclosure, offline mode, and adapter controls;
10. `EXIT STATUS`, defining every status from [`PRODUCT.md` section 13](PRODUCT.md#13-cli-surface);
11. `LIMITATIONS`, stating residual races, capability-dependent behavior, and version 1 exclusions;
12. `REPORTING BUGS`, linking to the canonical upstream issue tracker;
13. `SEE ALSO`, including at least `pkg(1)`, `apt(8)`, and `du(1)`.

The prose uses operator-visible terms from `PRODUCT.md`. It never promises guaranteed reclaimed bytes,
rollback, complete access, file-level package-manager effects, or support beyond evidenced adapter
versions and capabilities.

## Synchronization

`--help` is the concise command reference; the manual page is the complete installed reference.
The two artifacts use one option definition in production code or one checked generated data source.
They must agree on option spelling, arity, conflicts, exit status, and unattended-operation absence.

The manual page may summarize keyboard behavior, but the canonical key map remains
[`UI_GUIDELINES.md`](UI_GUIDELINES.md#key-map). Configuration details remain canonical in
[`CONFIGURATION.md`](CONFIGURATION.md). Safety wording links back to stable identifiers in
[`REQUIREMENTS.md`](REQUIREMENTS.md) instead of creating new guarantees.

Every behavior change affecting CLI, keys, configuration, files, network use, safety, limitations,
or exit status updates the manual page in the same change.

## Rendering and verification

Documentation checks must:

- reject roff diagnostics from `mandoc -Tlint` or a strict parser with the same checks;
- render the page in a fixed test environment and reject unresolved macros or escapes;
- compare the documented options and statuses with the production CLI definition;
- verify every required heading and stable safety-reference identifier;
- install into a temporary prefix and resolve the page through `man -M`;
- search rendered output for accidental absolute build paths, timestamps, and control bytes.

The package acceptance test repeats installation and lookup inside supported Termux environments.
A host renderer is syntax evidence only because it cannot prove Termux installation paths or width
behavior.