Command Line Interface
======================

The package installs two console scripts:

``planner``
   Primary command.

``tuxfan-planner``
   Backward-compatible alias.

Run ``planner --version`` or ``planner -v`` to print only the current version
number and exit successfully, without loading a plan or configuration. Both
console scripts support these options.

Help Topics
-----------

Each command and scoped ``list`` view starts with a one-line purpose statement
below usage, before its arguments and options. Help then uses short Examples,
Notes, and Related sections, followed by a reference to the relevant manual.
The examples use fictional files and can be copied as command patterns.
Notes keep the essential defaults, conflicts, write restrictions and recovery
requirements close to the command. Exhaustive schema rules, rendering details
and migration guidance belong in this reference and the configuration/export
manuals. Run ``avail FIELD`` for a field's actual choices.

For example, ``planner export --help`` shows DOCX, PowerPoint and PDF examples,
then explains the output suffix, Word requirement for PDF, template selection
and standard override. Table layout, numbering, typography, spacing and section
selection are documented in :doc:`export-options` and :doc:`configuration`.

Scoped ``list`` help retains field choices, concise filter syntax, relation
targets and examples. ``show`` help demonstrates qualified names instead of
printing every field alias; use the object-view help and field templates to
explore fields, and the command reference below for the full behavior. All accepted field names and aliases retain their existing parsing.

``planner help`` displays top-level help. Command and topic aliases invoke the
same parser help as ``--help``, with the same exit status, formatting, colors,
environment information, and automatic paging:

.. list-table:: Help aliases
   :header-rows: 1

   * - Invocation
     - Equivalent
   * - ``planner help fields`` or ``planner fields help``
     - ``planner fields --help``
   * - ``planner help list tasks``
     - ``planner list tasks --help``
   * - ``planner list help tasks`` or ``planner list tasks help``
     - ``planner list tasks --help``
   * - ``planner help fields task`` or ``planner fields help task``
     - ``planner fields task --help`` (fields command help)
   * - ``planner config init help``
     - ``planner config init --help`` (config command help)

Place ``help`` once along a valid command/topic path. Real subcommands, such as
list kinds, have scoped help. Positional choices such as ``fields task``,
``config init``, and ``completion bash`` are validated but show their parent
command's help. Invalid topics exit with status 2 and show the nearest relevant
help on stderr. Valid help exits with status 0 on stdout without reading plans,
loading configuration, or initializing configuration files. Shared options such
as ``--config PATH`` retain their normal parsing and conflict rules.

Option values equal to ``help`` remain ordinary values. ``--`` ends alias
recognition; for example, ``planner list -- help`` passes a filename. A filename
can also be written ``./help``. Aliases do not apply after filenames or other
unrestricted positional arguments. Help topic paths must precede ``--``.
Bash, zsh, and fish suggest command/topic names in help requests instead of input
files, and offer ``help`` at command/topic boundaries.

Help and usage messages wrap at the configured width (80 characters by default), including environment
variable values and filtering examples.
Wrapped command descriptions align beneath the first word of their description,
including when the final wrapping at the configured width (80 by default) pass needs to wrap a command row.
Widths and indentation count visible text, excluding ANSI color codes from
argparse and planner styling.
Top-level help lists commonly used command flags as aligned option/description
entries under ``Command options (after COMMAND)``, with continuation lines
aligned beneath each description. Each description identifies the command that
accepts the flag; these are command options, not global options. ``FIELD`` is
a placeholder for exact supported list fields, such as ``label`` or
``status``. Run ``planner COMMAND --help`` for the complete command options.
On compatible terminals, this section uses a bold cyan heading, cyan option
names and arguments, and green command scopes. Descriptions remain plain.
Color is applied after wrapping to preserve alignment and the configured width limit.
Redirected output, ``NO_COLOR``, and ``TERM=dumb`` disable these colors.

Help and usage messages begin with ``tuxfan-planner`` on its own line, followed
by the current version on a line labeled ``Version:``. The project name is bold
on compatible terminals, honoring ``NO_COLOR`` and ``TERM=dumb``; the version
line remains regular weight.
In a source checkout, this follows ``pyproject.toml`` immediately after a version
bump; installed packages report their distribution version.
CLI errors appear red and ``UserWarning`` messages appear amber on compatible
stderr terminals; redirected output,
``NO_COLOR``, and ``TERM=dumb`` disable error color.

Input diagnostics include ``filename:line`` when a source location is known.
Funding warnings point to the input funding entry, including inherited parent
funding. Task and milestone validation errors identify their defining block;
YAML/Python syntax errors identify the parser's problem line. Export-options
validation errors also include source locations. Line numbers are one-based.
Literal Python task definitions can be located; dynamically computed task
entries may report only a filename. Missing files and command-line argument
errors do not invent an input line number.

Parent-only plan exports
------------------------

Set ``export.layout.multipart: parents`` in the general configuration (or a
per-standard override) to show one parent task entry per multipart group while
retaining standalone tasks. ``expanded`` is the default. This affects task
narratives/tables in Word/PDF, SVG cards and PowerPoint slides. Parent prose is
retained, child prose is omitted, mixed fields display ``Mixed`` and incomplete
timing is marked partial. Funding and readiness use the original parts.
Parents spanning activities are placed in the first part's activity with a
warning; subtotals retain the original assignments. Gantt charts and terminal
lists are unchanged. See :doc:`export-options` for aggregation and import limits.

Paging long output
------------------

Set ``TUXFAN_PLANNER_PAGER`` to a pager command, for example:

.. code-block:: bash

   export TUXFAN_PLANNER_PAGER='less -R'
   planner list

Planner pages output only when both stdin and stdout are terminals, ``TERM``
is not ``dumb``, and the displayed output exceeds the terminal height with one
row reserved for the prompt. Wrapped lines count toward the height; ANSI color
sequences do not. Terminal width, tabs, combining marks, and wide characters
are accounted for. Short output stays direct.

Automatic color detection uses the original terminal before starting the
pager, so ``list`` retains colors without ``--color always``. ``less -R``
preserves these ANSI colors. ``NO_COLOR`` and ``--color never`` still work;
disabling color does not disable paging. Redirected or piped stdout bypasses
paging and retains existing color behavior.

Paging applies to ``list``, ``list-detail``, ``summary``, ``schedule``, ``show``,
``avail``, ``fields``, and help printed to stdout. Stderr diagnostics, validation
results, completion scripts, editing prompts, export messages, and merge/split
reports remain direct. Unset, empty, or whitespace-only pager settings disable
paging. Quoted executable paths and arguments are supported; shell pipelines,
redirection, and shell expansion are not interpreted. If the command is malformed
or cannot start, output is printed directly. Quitting the pager early is normal.
Pager startup/exit does not change the planner command's success status.

Commands
--------

Prefix each command below with ``planner`` (or ``tuxfan-planner``).
An explicit input path overrides ``TUXFAN_PLANNER_DATAFILE``. For ``export``,
``export-gantt``, and ``composite``, the output path is always required; input
may be omitted only when that environment variable is set.

When ``TUXFAN_PLANNER_DATA_DIRECTORY`` is set, relative input filenames resolve
there first, then in the current directory if missing. This also applies to a relative default
filename from ``TUXFAN_PLANNER_DATAFILE``. Absolute inputs bypass the directory.
Output paths and export-options paths are unaffected; included YAML paths still
resolve relative to their containing files.

Read commands accept composite YAML plans, expanding ``!include`` directives
before plan validation. ``format`` formats the main file and recursively included
YAML sources in place. ``spell-check`` reviews prose across the main file and
included YAML sources in one session, preserving include directives.

Field selectors are positional names, consistently across ``list``, ``show``,
``avail``, and ``fields``; the former ``--FIELD`` selectors are rejected.
Use ``planner list tasks.yaml label status``, ``planner show tasks.yaml tags``,
``planner avail status``, or ``planner fields task``. With a default input in
``TUXFAN_PLANNER_DATAFILE``, use ``planner list label status`` and
``planner show tags``. List accepts multiple names and permits options before,
between, or after them. Filtering and rendering controls such as ``--only``
and ``--color`` remain options.

``validate [task_file] [--config PATH] [--standard VERSION]``
   Use ``--standard legacy|asc-v4|asc-v6`` to override ``export.standard`` and
   resolve the matching configured export rules for validation. Without it,
   the configured standard applies. All configuration blocks remain validated,
   including inactive ones. This does not generate an export or modify the
   configuration file. For example::

      planner validate plan.yaml --config configs/asc.yaml --standard asc-v4

   Validate a YAML or Python plan file. Task ``priority`` and ``risk`` are optional
   for every status. Omitted priority is unassigned; omit risk or use
   ``risk: []`` for no risks. Supplied values retain validation. Successful output is limited to
   ``Validation: PASS`` and counts of activities, expanded tasks, milestone
   definitions, activities, configured fiscal years,
   work item references, project dependency definitions, project and inline task risks,
   and emitted warnings. Activities use the same grouping
   as ``list`` and exports; unused activities count only under
   Activities. Work item references count per task, including inherited
   references on multipart parts. Warnings follow the active warning filters
   and appear on stderr with their original source locations and terminal
   styling, after the ``Warnings: N`` statistics line. Output is flushed before
   warning details so redirected streams preserve that order when combined.
   Warnings collected before a validation failure are also shown beneath a
   warning-count line. Plan metadata and narratives
   are omitted. Failure prints ``Validation: FAIL`` and an error diagnostic
   to stderr, with exit status 1; success exits with status 0.
   ``PASS`` is green and ``FAIL`` is red on compatible stdout terminals;
   redirected output, ``NO_COLOR``, and ``TERM=dumb`` keep the status plain.

``show [task_file] FIELD``
   Print unique non-empty values used by exactly one scalar or scalar-list
   field, one per line, sorted alphabetically ignoring case, with spelling and
   case preserved. Exact duplicates are removed; case variants remain distinct.
   Empty results produce no output. Normal input environment variables,
   validation, includes, and multipart inheritance apply.
   Examples: ``planner show tasks.yaml tags`` or
   ``planner show tasks.yaml assignees``.

   Unqualified names collect all applicable contexts, matching the canonical
   field names used by ``list``. Qualified names restrict the context:
   ``tasks.status``, ``workitems.status``, ``risk.type``,
   ``milestones.id``, ``execution.activities.label``, ``execution.description``,
   and ``plan.project``. Scalar lists are flattened, including tags,
   dependencies, task milestone references, assignees, and deliverables.
   Structured containers (tasks, risk, workitems, funding, execution) are not
   selectable. ``milestones`` selects task milestone references; definition
   fields use qualified names or shared leaf names.
   Exactly one field is required; abbreviations are rejected.

   Names follow plan YAML keys, so a task's activity is ``activity``. These
   aliases give identical output:

   * ``activities`` for ``activity`` (the collection name used by ``list`` and
     ``--only``)
   * ``activities.id``, ``activities.label`` and ``activities.description`` for
     ``execution.activities.*``
   * ``tasks.risk.type``, ``tasks.risk.level``, ``tasks.risk.description`` and
     ``tasks.risk.mitigation`` for ``risk.*``

   ``risk.*`` (and ``tasks.risk.*``) selects inline task risks; ``risks.*``
   selects project risk definitions.

``fields TYPE``
   ``planner fields colors`` prints every effective terminal color as a plain
   YAML ``terminal.colors`` mapping, honoring ``--config``. Paste this fragment
   into the general configuration; it does not load a plan. ANSI defaults use
   conventional hex equivalents. See :doc:`configuration`.

   Print a copyable YAML mapping template without reading a data file.
   Supported types are ``config``, ``colors``, ``plan``, ``task``, ``workitem``, ``risk``,
   ``project-risk``, ``dependency``, ``milestone``, ``deliverable``, ``execution``,
   and ``activity``. Plural aliases ``tasks``, ``workitems``, ``project-risks``,
   ``risks``, ``dependencies``, ``milestones``, ``deliverables``, and ``activities``
   are accepted, along with ``execution.activities``. ``risk`` is a private task
   risk; ``risks`` is a project risk definition. Types are exact; missing or unknown types are usage
   errors (exit status 2).

   Output contains only YAML and YAML comments, without terminal styling or
   prose banners. Keys follow canonical input field order; nested mappings
   are expanded. Fixed-choice fields list all valid choices in inline comments,
   with severity order for risk levels, and open/closed order
   for work item statuses. Free-form fields use example text or empty values.
   Examples are starter values, not schema defaults. Optional completed periods,
   alternative fiscal-year lists, and multipart syntax are commented out to
   keep the active example valid.

   ``planner fields task`` prints one task mapping. Place it under ``tasks``
   as a list item with appropriate indentation. Other mapping fragments also
   need their containing key or list. ``planner fields plan > new-plan.yaml``
   writes a complete starter plan; replace example values before use.
   ``planner fields config > new-config.yaml`` writes a complete configuration
   template from packaged defaults, including commented optional allowlists and
   export alternatives. It does not read or initialize the user configuration;
   ``--config`` is ignored for this template, even if it names an invalid or
   missing file. Other types use the active configuration for vocabulary examples.
   Task ``site`` and ``bnr`` examples honor configured allowlists.
   ``type`` accepts one built-in ID or a list: labor, contract, equipment, services, nonlabor.
   Omitted site/bnr allowlists leave those IDs unrestricted.
   Input environment variables and export options do not affect this command.

``avail FIELD``
   Print finite schema options, one per line, without
   loading a plan or consulting input environment variables. Exactly one field
   is required. ``status`` prints separate labeled groups explaining task
   statuses (including blocked and unfunded) and work item entry statuses.
   Task statuses are alphabetical with ``closed`` last; work item statuses are ordered open, closed.
   ``priority`` lists
   configured task priority IDs in declaration order.
   ``level`` lists risk levels in severity
   order: low, medium, high, extreme.
   ``risk.type`` lists required risk types: technical, schedule, operational,
   external, performance.
   ``priority`` and ``category`` list configured IDs, labels, and descriptions.
   ``type`` lists the built-in task types: labor, contract, equipment, services, nonlabor.
   ``site`` and ``bnr`` list configured task IDs; an empty allowlist
   prints nothing, and an omitted allowlist produces an operational error.
   These fields, ``status``, ``priority``, ``level``, ``risk.type``, ``deliverables.type``, and
   ``deliverables.status`` are offered in help and completions. The qualified deliverable type field
   lists paper, document, presentation, release, software, dataset, model, service,
   training, demonstration, assessment, design, hardware. The qualified deliverable status field
   lists required, planning, blocked, submitted, complete, closed.
   On compatible terminals, reusable IDs and built-in choices use bold magenta;
   explicit ``table_entry`` values use cyan. Labels, descriptions and headings
   remain plain. Redirected output, ``NO_COLOR`` and ``TERM=dumb`` disable
   automatic color. Paging preserves these colors. Colored and plain output
   use the same layout and ordering.
   Output wraps at the configured width (80 visible columns by default), excluding ANSI styling and accounting
   for wide characters and combining accents. Priority/category IDs appear on
   their own lines, followed by indented Label, Description, and optional
   ``table_entry`` fields. Field continuations align beneath their values and
   blank lines separate records. Other fields keep one choice per line, wrapping
   unusually long values when needed.
   ``planner avail colors`` lists terminal palette attributes, default/effective
   values, and colored hex values. ``--color auto|always|never`` controls all avail
   colors. Configure overrides through ``terminal.colors``; see
   :doc:`configuration`. Standard ANSI default hex values are conventional
   equivalents because terminal themes can change their actual appearance.
   Use ``planner show FILE FIELD`` for values actually used in a plan.
   Unsupported fields, unknown fields, containers, missing fields, and multiple fields are usage
   errors (exit status 2). Use ``--help`` to see all selectable field names.

``merge task_file TASK_ID TASK_ID... --id PARENT_ID --label LABEL --output output.yaml``
   Merge at least two standalone tasks defined in this YAML file into one
   multipart task. Accept a raw task-list fragment or a mapping containing
   ``tasks``; a complete plan is not required. The parent replaces the earliest
   selected task, and parts follow source declaration order, regardless of
   identifier order on the command line. Identical shared fields may move to
   the parent; differing values and funding remain on parts. The parent ID
   must be new. Expanded part IDs generally gain its prefix.
   Dependencies between merged parts retain short sibling IDs; references from
   other tasks are rewritten to expanded IDs. The loader resolves both forms to
   the same expanded task identifiers in their respective scopes.

``split task_file PARENT_ID --output output.yaml [funding {parts,equal}]``
   Replace a locally defined multipart parent with standalone tasks in part
   declaration order. Materialize inherited parent fields, honoring explicit
   part overrides and clears. Retain expanded IDs, resolve sibling references,
   and replace dependencies on the removed parent with all resulting IDs.

   A parent funding field requires an explicit policy. ``--funding parts``
   preserves effective part funding; inherited parent amounts can multiply
   totals. ``--funding equal`` replaces part funding with equal shares of the
   parent budget, preserving whole cents and assigning remainder cents to
   earlier parts. It requires a parent budget with whole-cent numeric amounts;
   unsuffixed amounts follow the planner convention of thousands of dollars.

Both commands require explicit input and output paths, use exact identifiers,
and never change the source or overwrite existing output files. Relative inputs
respect ``TUXFAN_PLANNER_DATA_DIRECTORY``; outputs remain relative to the current
directory. ``TUXFAN_PLANNER_DATAFILE`` does not supply these commands' input.
They preserve YAML comments and scalar styles where possible, BOMs, and newline
conventions, though indentation may normalize. Values already written as ``>``
or ``|`` blocks keep their style; other long prose becomes a ``>`` block and
multi-line text a ``|`` block. Python is not supported.

The report includes ID mappings, local dependency rewrite counts, funding
policies and local before/after totals where available. References are rewritten
only inside the supplied document. Includes remain external and their relative
paths are rebased to preserve their targets when the output directory changes.
Tasks must be selected in their defining file, not through an include.

Fragment checks validate supplied fields, duplicate visible IDs and visible
dependency cycles. Unresolved external dependencies, milestone and execution
references, missing required fields and fields supplied through includes require
the containing plan. Tasks containing include directives are left for contextual
validation. Successful output reports that full-plan validation is pending.
Review the mapping and funding report, update references in other files, and
validate the assembled plan after replacing the fragment. Malformed YAML,
recursive aliases, duplicate YAML keys, invalid selections, collisions and local
cycles fail with exit status 1 without writing output. Missing command arguments
are usage errors (exit status 2).

``composite [task_file] output_file [--nested]``
   Expand YAML ``!include`` directives into a standalone YAML output file.
   Input defaults from ``TUXFAN_PLANNER_DATAFILE``; output is required.
   Expansion preserves list order, defaults, and multipart definitions without
   requiring task-schema validation. Input files cannot be overwritten. Long
   prose is written as ``>`` blocks and lists as ``|`` blocks.
   ``--nested`` moves plan tasks/milestones/deliverables beneath execution and
   project dependencies/stakeholders/users/risks beneath resourcing. Values and
   ID references are retained; ambiguous duplicate locations are errors.
   See :doc:`composite` for syntax, examples, and expansion rules.

``format [task_file]``
   Format a data file and its included YAML sources in place. An explicit path overrides
   ``TUXFAN_PLANNER_DATAFILE``. YAML (``.yaml``/``.yml``) uses
   planner's built-in style, with no external tool: two-space indentation,
   long prose as ``>`` blocks, multi-line text and lists as ``|`` blocks, and
   collapsed blank-line runs, keeping authored blocks, comments, tags, anchors
   and explicit nulls. Python (``.py``) uses Black from planner's Python
   environment; install Black
   with ``pip install 'tuxfan-planner[format]'`` (or ``pip install -e '.[format]'``
   in a checkout).

   YAML formatting follows nested ``!include`` directives, formats each distinct
   source once, and preserves directives and file boundaries. Include paths are
   relative to their containing files. Python formatting operates on one file
   without executing it; full plan validation is not required. YAML structure/values and include references are checked before
   saving, and source encoding and line endings are retained. All results are
   prepared and checked before saving; invalid/missing includes, cycles, or
   formatter failures leave all sources and backups untouched. Changed files
   receive numbered ``.bak`` backups and are saved atomically; already formatted
   files remain untouched. Missing dependencies or formatter failures produce
   an error. Saves are atomic per file, not across the set; a later write failure
   may leave earlier files formatted. CMake's ``format`` target separately formats
   planner source code.

``spell-check [task_file] [--lang LANGUAGE] [--personal DICTIONARY]``
   Interactively review prose with the external Aspell executable. The default
   language is ``en_US``. Install Aspell and a dictionary separately from pip
   (``brew install aspell`` or ``sudo apt install aspell aspell-en``).
   The task file can default from ``TUXFAN_PLANNER_DATAFILE``.

   Prompts show the file, field, line, context, and numbered suggestions. The
   exact occurrence under review appears in bold red on color-capable stdout
   terminals; other occurrences remain unhighlighted. ``NO_COLOR``, ``TERM=dumb``,
   and redirected output keep context plain. Highlighting does not change source
   text or text sent to Aspell. Numbered suggestions appear in columns sized to
   the terminal, capped at ``max_width`` columns (80 by default; also the fallback width). Numbers increase
   down each column, preserving Aspell's ranking and all available choices.
   Narrow terminals use fewer columns, and long suggestions wrap. Choose
   a suggestion number, ``r`` to replace manually, ``i`` to ignore once, ``a`` to
   ignore for the session, ``d`` to add to the personal dictionary, or ``q`` to
   cancel. A final summary and save prompt precede any source/dictionary writes;
   the default is to discard. An interactive terminal is required. Cancellation
   before saving leaves staged changes unapplied.

   With an English dictionary, valid numeric ordinals such as ``2nd``, ``30th``,
   and ``111th`` do not trigger suffix warnings. Standalone suffixes, malformed
   ordinals such as ``22th``, and embedded alphanumeric strings remain subject
   to normal Aspell checks. Other dictionary languages are unaffected.

   Composite YAML is supported, including scalar and list fragments. The include
   graph is checked before Aspell starts; fields retain their original filenames,
   lines, and context. Each source string is reviewed once, even when included
   repeatedly. Text shared between prose and structural uses requires manual
   review. Ignore-all and dictionary additions span the session. A combined
   summary groups corrections by file; one final confirmation controls saving.

   Checks cover prose in plan metadata, execution narratives, task fields,
   milestones, deliverables, and risks, including notes. IDs/references, schema
   keys, dates, funding, enums, and Markdown link destinations are skipped.
   Source strings are checked once before inheritance or multipart expansion.
   Valid source syntax is required; full plan validation is not.

   Edits preserve comments, quoting, indentation, block styles, line endings,
   and encoding. Saves validate syntax, retain a ``.bak`` backup (numbered when
   necessary), and atomically replace each changed source. All sources and any
   explicit or discovered dictionary are checked for concurrent edits before saving. Multi-file
   and dictionary saves are not one atomic transaction; later failures report
   the sources already saved.
   Python files are inspected without execution; computed values, raw strings,
   concatenated literals, and spellings encoded with escapes may require manual
   editing. Use a resolved file path when saving through symbolic links.
   ``--personal`` selects an Aspell personal dictionary, overriding discovery;
   relative paths are resolved from the current directory. Otherwise, the nearest
   ``.planner-words.pws`` in the main input's directory or its ancestors is used.
   Without one, Aspell uses its standard personal dictionary. A discovered file
   must be readable and valid; invalid nearer files do not fall back to ancestors.
   The selected dictionary is loaded and reported before prompts. Explicit paths
   can name a new dictionary, created only when confirmed additions are saved.
   Composite files share the dictionary selected from the main input; included
   directories do not override it. Selecting a project dictionary replaces the
   usual personal dictionary while retaining the installed language dictionary.
   Missing Aspell/dictionaries produce an error. Other commands do not require
   Aspell.

   An example English project word list (use base language ``en`` in the header;
   ``--lang en_US`` still selects the spelling variant)::

      personal_ws-1.1 en 3 utf-8
      FleCSI
      FleCSolve
      Kokkos

``list KIND [task_file] [FIELD ...] [--color {auto,always,never}] [--only SELECTORS]``
   List a top-level plan element using its canonical field name as KIND.
   Compatibility views ``activities``, ``workitems``, ``risks``, and ``plan``
   retain their behavior. Each kind has its own
   help and scoped field choices. Omit task_file when the input environment
   default is set. See the object-view reference below.

``list [task_file] [FIELD ...] [--color {auto,always,never}] [--only SELECTORS]``
   Without fields, display the full terminal planning document: metadata,
   fiscal coverage, execution description/activities, milestone and
   deliverable definitions, and numbered task narratives with category labels
   and IDs, planning attributes, notes, work items, and risks. Include empty
   sections and unreferenced definitions. Export settings do not restrict this
   output. Omit the filename to use the normal input environment default.

   ``planner list --help`` documents ``KIND``, ``task_file``, and ``FIELD``
   together under positional arguments. ``KIND`` enumerates all supported views,
   including compatibility views. The primary top-level elements match
   ``export.elements``::

      portfolios
      project
      priority
      managers
      pocs
      summary
      background
      fiscal_range_begin
      fiscal_range_end
      fiscal_years
      fiscal_current
      planned_value
      actual_value
      potential_value
      execution
      milestones
      deliverables
      tasks

   Select one before the filename, for example ``planner list summary plan.yaml``
   or ``planner list execution plan.yaml``. With a default input, kinds take
   precedence over field projections. To combine projections, put the filename
   first: ``planner list plan.yaml project summary tasks``. Prefix filenames
   matching kind names with ``./``. Compatibility views remain available and
   have individual help commands.

   Explicit ``list tasks FILE`` retains the original compact task-only layout;
   ``list plan FILE`` retains its scoped metadata/relationship summary.
   With no kind, use ``list FIELD`` to specialize output by any supported field identifier,
   such as ``label``, ``status``, ``assignees``, or ``mitigation``.
   ``FIELD`` is a placeholder for the exact input field name. Combine field
   names to display several fields. Nested selections retain the activity,
   task, and item context needed to identify their values. Container names such
   as ``workitems`` show their complete contents. Combine field selection with
   ``--only`` to filter tasks before displaying the requested information.
   Run ``planner list tasks --help`` for supported scoped task fields, or see the
   field-selection reference below.

   The explicit ``list tasks`` view prints concise tasks in Word activity order, using the
   same activity letters,
   task numbers, and numbered dependencies as the Word export. Parts of a
   multipart task appear together within each activity, ordered by end date
   with declaration order breaking ties, including when using ``label`` or
   other field names. Without field names, each multipart group has an
   unnumbered parent heading displaying its label and ID, such as
   ``Airframe Development [AIRFRAME]``. Parts are indented beneath the heading,
   with descriptions and other details one level deeper. The heading appears
   once per group within an activity, including when ``--only`` selects just
   some parts. Part numbers and dependency references remain unchanged;
   standalone tasks retain their existing indentation. Each task shows
   its label and ID in its heading. Children show their source part ID, such as
   ``Task A.1: Baseline Design [BASELINE]`` beneath parent ``[AIRFRAME]``;
   standalone tasks show their task ID. Expanded child IDs such as
   ``AIRFRAME_BASELINE`` remain the identifiers for dependencies and selectors;
   local part IDs are not selector aliases. Each heading is followed by its description,
   a ``Note:`` line when present, dependencies when present, and status.
   Child and standalone IDs use the shared ID styling; closed task IDs remain bold gray and unfunded task IDs use bold muted amber. Field-selected output retains its existing layout.
   Task labels use normal cyan, with explicit Markdown emphasis preserved.
   Description text uses canary (``#ffff99``), including nested descriptions,
   field projections and configured lines. Explicit configured field colors
   override this default; descriptions use canary even in closed/unfunded task
   blocks, whose headings and status fields retain their muted colors. ``layout.context_colors: false`` disables this semantic color.
   If a parent or task heading would exceed the configured width (80 visible columns by default), its bracketed ID
   moves to a separate line indented two spaces further. Long labels and IDs
   wrap within the configured width (80 by default); widths account for Unicode characters and exclude
   ANSI color codes.
   Notes use the same Markdown rendering and 80-terminal-column wrapping as descriptions,
   with gray text for closed tasks and muted amber for unfunded tasks. Tasks with funding show
   identified fiscal years on one line, such as ``Funding: $500K (FY27),
   $250K (FY28)``; dollar amounts are light green when color is enabled.
   A ``Funded Total:`` line at the bottom covers every configured fiscal year,
   including years with ``$0K``, and reports amounts in thousands of dollars.
   Every part of an ``unfunded`` task entry, including its label, appears muted amber
   in colored output.
   Linked activities also show their activity descriptions.
   Activity and task labels and descriptions interpret inline Markdown:
   ``**bold**``/``__bold__``, ``*italic*``/``_italic_``, and ``[label](URL)``.
   Links display as ``label (URL)``; supported schemes are http, https, and mailto.
   Emphasis uses terminal styles when color is enabled; plain output removes
   the formatting markers and retains link destinations. Escaped/unmatched
   markers and underscores within identifiers remain literal.
   Plain text sections also accept unordered Markdown lists: start each item
   on its own line with ``* ``, ``- ``, or ``+ ``. Use a YAML literal block
   (``|``) to preserve those newlines. Items render as bullets, with nested
   indentation and hanging wraps; inline emphasis and links still apply.
   Within these sections, consecutive prose lines and indented bullet
   continuations reflow to the available width. Blank lines separate paragraphs,
   and nested bullets retain their indentation. This also applies to ``|-``
   blocks, so prose can be wrapped for readability in the YAML source.
   Escape the marker (for example, ``\* ``) to keep it literal.
   Description and note wrapping counts wide characters as two columns and
   combining marks as zero, ignoring ANSI styling. Descriptions wrap at 80 terminal columns.
   List views share one structural hierarchy. Main headings are bold muted cyan,
   framed above and below by full-width muted orange double rules. Subsections
   have the same bold muted cyan headings and indented thin gray rules. Activity headings use muted cyan and record
   titles use cyan; lighter gray item separators and increasing indentation
   distinguish deeper records. The complete plan groups activities, tasks,
   milestones and deliverables under Execution, and project dependencies,
   stakeholders, users and risks under Resourcing. Configured lists retain
   element declaration order, repeating a parent heading when necessary.
   Scoped views frame their selected section at the top level. ``list-detail``
   frames its metadata sections and task section too. Rules end at column 80;
   wrapping accounts for nesting, Markdown, ANSI codes and Unicode widths.
   IDs retain bold magenta; status/risk/funding colors and explicit configured
   styles remain in effect, including muted closed and unfunded entries.
   Field-only selections and the ``label`` outline remain compact without
   structural rules. Color is automatic on compatible terminals;
   ``--color`` and ``NO_COLOR`` retain their existing behavior.

   ``label`` alone gives the compact label outline; other field selections
   use contextual headings and omit unrelated fields and funding totals.

``list-detail [task_file] [--only SELECTORS] [--color {auto,always,never}]``
   Print validated task details in planner sort order. Ongoing tasks show their
   funded fiscal years and twelve months of duration per funded year. Empty
   dependency fields display ``None``. Work item attributes include their labels,
   IDs, inferred types, statuses, assignees, and descriptions when supplied.
   Field selection is available only on ``list``.
   Terminal output uses cyan headings/task labels, blue field labels, subdued
   magenta IDs and references, canary description text, status colors, and risk severity colors.
   Funding totals are green. Closed task blocks stay gray; unfunded task blocks use muted amber, with matching bold IDs. The default ``--color auto`` honors ``NO_COLOR``, ``TERM=dumb``,
   and stdout redirection; ``always`` and ``never`` override detection. Existing
   text, literal Markdown, ordering, and layout are preserved. Automatic paging
   retains terminal color behavior. Bash/Zsh/Fish complete the color option.

``summary [task_file]``
   Print task counts by activity and milestone ID (``None`` when omitted).
   Metadata output includes defined milestone labels, deadlines, descriptions,
   and deliverables. Funding totals use configured
   fiscal years, or years inferred from task funding when no plan years are set.

``schedule [task_file]``
   Print dependency-aware task order with ``COMPLETE``, ``ACTIVE``, ``ONGOING``, ``PLANNING``,
   ``UNFUNDED``, ``READY``, ``BLOCKED``, or ``CLOSED`` state. Ongoing task timing follows its
   funded fiscal years. Planning placeholders remain ``PLANNING`` and display
   ``Unscheduled`` until ``start`` and either ``expected`` or ``end`` are supplied; unknown
   duration displays as ``Unspecified``. Funding estimates do not create their
   schedule. Closed tasks require only id, label, description, category, and status; they
   also display ``Unscheduled`` until both timing fields exist. Closed tasks use
   gray list styling; unfunded tasks use muted amber. Tasks without an activity
   appear under ``Unassigned`` in all displays. Top-level ``project`` selects only
   plan metadata; there is no task project field.
   Work item references appear in task attributes.

``import input.docx [output.yaml] [--config PATH] [--update VERSION]``
   Import visible content from a planner-style Word document into a validated
   YAML draft. The input filename is required; output defaults to the input path
   with its final suffix replaced by ``.yaml``, in the same directory. For example,
   ``planner import plans/proposal.v2.docx`` writes ``plans/proposal.v2.yaml``.
   An explicit output filename overrides this default. Relative paths use the
   current directory; planner environment overrides are ignored. Input must be
   ``.docx`` and output ``.yaml`` or ``.yml``. Existing output files and symlinks
   are refused. Publication is atomic and exclusive; the source is unchanged.

   Missing task IDs use uppercase ASCII label words joined by underscores.
   Common connectors and routine terms such as development/improvements are
   omitted; preparation shortens to ``PREP``. For example, ``Engine Model
   Development`` becomes ``ENGINE_MODEL``. Qualifiers remain, without a fixed
   word limit. Accents normalize to ASCII; labels without usable words fall
   back to ``TASK``, and numeric labels receive a ``TASK_`` prefix. Recovered
   explicit IDs are preserved and reserved before allocating generated IDs.
   Collisions receive ``_2``, ``_3``, etc., in document order, avoiding project
   dependency IDs and expanded multipart task IDs. Existing local part IDs are
   retained under the new parent ID. Relationships use the resulting IDs.

   Before falling back to ``planning``, missing forecast timing is inferred
   from positive annual task funding. Missing start uses ``M1Q1`` of the first
   positive year; missing end uses ``M3Q4`` of the last positive year when no
   duration was recovered. Recovered dates and durations are preserved. These
   bounds form one continuous span, including any intervening funding gaps.
   Allocation parts use their own effective funding and inherited task fields.
   Report notices and YAML comments identify inferred fields for review.
   Zero, absent, or placeholder amounts do not provide dates; an aggregate
   amount alone cannot establish years. Recovered ``unfunded`` status is retained
   when timing can be inferred. Missing status or unrecoverable required timing
   still becomes ``planning``. Ongoing timing remains funding-driven and actual
   completion dates are never inferred.

   When a selected export omitted a risk's type, the importer uses ``technical``
   as a placeholder and records a review notice in the report and draft comments.
   Explicit unknown risk types fail validation.

   The importer detects ``legacy``, ``asc-v4``, and ``asc-v6`` output contracts from Word
   properties, falling back to recognizable ASC version 6 template headings.
   Unknown explicit versions are errors. No upgrade is performed unless
   ``--update asc-v6`` is supplied. This migrates an older draft, adds empty
   optional resourcing fields, records the target version in YAML comments,
   and reports missing resourcing/reporting information. Funding-based forecast
   inference applies to imports with or without this flag. Migration does not
   supply other missing facts or modify export configuration.
   Select ``export.standard: asc-v6`` when exporting the resulting draft.
   ASC v4 is recognized from export metadata or a ``Project Plan Template (v4)``
   heading. Background prose, existing resourcing information, and milestone
   reporting levels are retained during ``--update asc-v6``; no facts are
   invented. Unfilled instructional templates still fail without creating output.

   Tasks may be numbered (``1.``, ``A.1``) or lettered (``a.``, ``A.a``,
   table rows such as ``a – Name``); lettered task numbers are normalized internally; generated task IDs come from labels.
   A lettered list item starts a task only when it is the next letter in its
   activity, so ``i.``/``ii.`` sub-items stay in the task description.
   Schedule tables whose fiscal-year cells hold text rather than amounts, and
   tables with no fiscal-year columns, are kept as review notices.

   ASC imports recognize hierarchical task numbers, new table column names,
   numeric thousands-of-dollars amounts, milestone L1/L2 reporting levels,
   and external resourcing narratives. Funded/Unfunded is a funding indicator;
   it does not overwrite a more precise narrative task status. An unfunded
   task may still have annual amounts. A template without populated task
   narratives is rejected rather than importing instructional example rows.

   Recover metadata, execution narratives, milestones, deliverables, tasks,
   risk mitigation, and available table attributes and annual funding. Table
   rows join to narratives by activity/task number. IDs are generated
   deterministically; deliverable labels resolve references. Optional export
   options identify custom table headers. Supported inline prose formatting
   becomes Markdown. Unknown columns and ambiguous work item cells are reported;
   ambiguous work item text is retained in task notes.

   Word's automatic activity/task numbering and bullet lists are recognized,
   including inherited list styles. Activity and task labels may be separated
   from their descriptions by a colon or a spaced hyphen, en dash, or em dash.
   Funding continuation rows become allocation parts, preserving each B&R and
   annual amount with review comments. Standalone metadata headings and
   unbulleted contacts are accepted.

   Deliverables and milestones written as text become draft definitions:
   each bullet, numbered item, or ``FY27 – text`` / ``FY27: text`` line is one
   entry with a ``FIXME_n`` ID and label for you to rename. A numbered heading
   followed by bullets (``1. Activity A — Workloads``) prefixes each item's
   description. Deliverables get ``type: document`` and ``status: planning``,
   so drafts do not warn about missing producer tasks. Milestones get a
   deadline at the end of their stated fiscal year (``FY27`` → ``M3Q4FY27``),
   from the item or a preceding ``FY27`` heading; undated milestones use the
   plan's first fiscal year and keep their original date text, marked as a
   placeholder. Other text, such as plain paragraphs, stays in the summary.

   Long prose in the generated YAML uses folded ``>`` blocks and text with list
   items uses literal ``|`` blocks, wrapped near the configured width (80 by default); short values stay
   plain. Loading the file gives exactly the imported values.

   Top-level YAML fields and activities retain their first-appearance
   order in the input document. Task entries follow document order in the
   generated YAML; later CLI views and exports use normal planner task sorting.
   Blank lines and labeled comment dividers separate top-level YAML fields.
   One blank line separates list entries containing an ``id`` field at every
   nesting level, including tasks, milestones, deliverables, activities,
   and work items. The dividers use this format:

   .. code-block:: yaml

      #------------------------------------------------------------------------------#
      # Milestones
      #------------------------------------------------------------------------------#

      milestones:
      - id: MILESTONES_1
        label: Design review
        description: Review the design.
        deadline: M3Q4FY27

      - id: MILESTONES_2
        label: Final review
        description: Review the finished work.
        deadline: M3Q4FY28

   Selected Word exports recover visible IDs, references and task fields using
   semantic paragraph markers. Older or manually authored documents can omit
   original IDs, multipart structure, task milestone links, dependencies, dates,
   priorities, and some statuses. Tasks become planning
   placeholders unless a closed marker or sufficient completion information is
   available. A completion year alone does not establish a completion month.
   Funding totals do not establish annual allocations. Missing values and
   assumptions appear in YAML review comments and the import report, with
   document block/table-row locations. Review statuses and timing before using
   the imported plan. Ambiguous deliverable references, unrecognized task
   structures, and invalid generated plans fail without publishing output.

Unfunded tasks use ANSI color 137 (``#AF875F``, muted ochre) in terminal
listings, and pale amber ``#E8D5A8`` in plan SVG and Gantt SVG/PowerPoint.
Closed task entries stay gray, with export fill ``#D1D5DB``.

``export [task_file] output_file [--config PATH] [--standard VERSION] [--template PATH]``
   Configuration ``export.standard`` accepts ``legacy`` (the unchanged default),
   ``asc-v4``, or ``asc-v6``. V4 defaults to normal spacing, underlined headings,
   portrait tables, and v4 content/column order. Explicit selections and layout
   settings override profile defaults. See :doc:`export-options` for examples.
   Use ``export.standards.<standard>`` for per-standard overrides of shared
   export settings. Layout mappings merge; content selections and ordered lists
   replace. All blocks are validated, including inactive ones. Examples are
   included in ``planner fields config``.

   ``--standard legacy|asc-v4|asc-v6`` overrides ``export.standard`` for this
   invocation and selects the corresponding configured rules. Without it, the
   configured standard remains the default. The option applies to Word, PDF,
   SVG, and PowerPoint export; it does not modify configuration or plan files.
   All configuration blocks remain validated, including inactive ones. For example::

      planner export plan.yaml plan-v4.docx --config configs/asc.yaml --standard asc-v4

   Task input accepts ``start`` with either ``expected`` (inclusive months) or
   ``end`` (inclusive fiscal period). ``line: [start, end]`` displays effective
   dates for either input form; redundant supplied duration/end values must agree.

   In configured task lines, ``{field: number, format: short}`` prints a bare
   number such as ``A.1.1``; ``format: full`` (the default) retains ``Task ``.
   This changes presentation only, preserving IDs, numbering, and table output.
   See :doc:`export-options` and ``planner fields config`` for the YAML syntax.

   Formatting instructions accept boolean ``heading`` beside a standalone
   field, as a grouped-line default, or on an individual line field. For example,
   ``- {description: null, heading: false}`` hides ``Description:``. Standalone
   field labels are enabled by default, including descriptions. Structured-field
   instructions apply the setting to the parent and selected child labels;
   section titles and table headers are separate.

   Write a Word plan for ``.docx``, an SVG plan for ``.svg``, a PDF plan
   for ``.pdf``, or editable PowerPoint plan slides for ``.pptx``. PDF export converts the same Word document using Microsoft
   Word, preserving its pagination and formatting. It requires Word installed
   and activated on macOS or Windows, and may prompt for automation permission
   on macOS. macOS conversion files are staged inside Word's own sandbox,
   avoiding per-export file-access requests. Planner copies the finished PDF
   to the requested destination and removes temporary files. Windows uses a
   temporary folder beside the output. Word remains open after conversion.
   Word versions and installed
   fonts can affect pagination, as with a manual PDF save. Conversion failures
   leave an existing PDF unchanged. On Linux, export ``.docx`` and save as PDF
   in Word on a supported system. PDF accepts the same export options, custom
   table labels/alignment as Word.
   Merged activity and parent-task table rows have horizontal padding to keep
   their labels clear of cell borders.
   Activity headings stay with their first task row across page breaks;
   multipart parent headings stay with their first part.
   Parent headings throughout Word/PDF narratives and PowerPoint continuation
   slides likewise stay with their first child where space permits. Explicit
   page/section boundaries remain intact, and larger sections can continue.
   Word/PDF tables size all columns from their displayed words and bold headers,
   keeping B&R codes and values such as Unfunded together where space permits.
   Multiword text can wrap between words. Export warns when estimated minimum
   widths exceed the page; orientation, margins, and font size remain unchanged.
   Configure narrative text with ``export.layout.font_size`` and Word/PDF
   table text independently with ``export.layout.task_table.font_size``.
   Sizes are numeric points in half-point increments, from 1 to 1638.
   Word/PDF defaults are 12 pt for body text and 10 pt for tables. Omitted body
   sizing preserves SVG/PowerPoint native sizes; explicit sizing adjusts their
   wrapping and pagination. Display titles and markings retain their sizes.
   Table left/right cell margins are 2.7 pt per side, or 3 pt for merged
   activity/parent rows.

   Set ``export.layout.spacing`` to ``normal`` for reference-document paragraph
   spacing or ``tight`` (the default) for the compact layout. The setting applies
   to Word/PDF, SVG and PowerPoint exports, with pagination adjusted as needed.
   Following portrait tables, Word/PDF inserts an 8 pt paragraph gap in normal
   mode or 4 pt in tight mode; cell spacing and explicit page breaks are retained.
   It does not affect terminal list or Gantt chart spacing.
   The output-standard identifier is retained in metadata and is not printed
   in exported content.

   Example: ``planner export tasks.yaml plan.pdf --config options.yaml``.
   Word narratives identify closed tasks with a gray ``[CLOSED]`` marker.
   SVG export warns when task IDs produce empty or duplicate SVG element IDs,
   including conflicts with its dependency marker. Export still completes with
   the existing IDs. Warnings name the tasks and include source locations when
   available. Only SVG plan export emits these warnings; validation, Word, and
   Gantt exports are unaffected.
   ``export.elements`` in the general configuration selects fields through
   nested boolean mappings. Task narrative fields and table columns are selected
   independently. ``task_table`` controls Word/PDF
   columns and totals. ``export.layout.task_table`` controls presentation without
   enabling content. Risk and mitigation appear within task narratives, without
   a separate mitigation section. Narrative notes use ``elements.tasks.note``; the retired
   note flag and legacy export option keys are rejected. Omitted/null elements
   enables everything; bare entries enable individual fields or branches, and
   an empty mapping selects no content. Full-plan validation
   and calculations remain unchanged. See :doc:`export-options` for the complete
   tree and migration instructions. ``--config PATH`` selects a complete config.

   PowerPoint exports editable plan slides without requiring Office. Templates
   (``template.pptx`` or ``template.potx``) are searched in
   ``TUXFAN_PLANNER_TEMPLATE_DIRECTORY``, then the current directory; otherwise
   the built-in design is used. ``--template PATH`` selects a specific
   ``.pptx``/``.potx`` file using a current-directory-relative or absolute path,
   bypassing template search. Missing or invalid files are errors. This option
   requires ``.pptx`` output. See :doc:`export-options` for template setup
   and slide formatting details.

   Example: ``planner export tasks.yaml plan.pptx --config options.yaml``.

``export-gantt [task_file] output_file [--from PERIOD] [--through PERIOD]``
   Write a fiscal-month Gantt chart. Use a ``.svg`` output path for a vector
   image or ``.pptx`` for slides with editable PowerPoint shapes. PowerPoint
   output uses one or more slides, split by activity, row count, and long time
   ranges. Bars use the stated ``start`` and an end month calculated from the
   ``expected`` duration, counting the start month as month one. Ongoing tasks
   instead have full-year bars for every year with positive funding, leaving
   gaps for missing or zero-funded years. Each task row keeps its number and label on one line
   when they fit, otherwise wraps the label at a word boundary within the
   two-line cell. Arrows leave the dependency bar's right edge and
   enter the dependent bar's left edge, routing around overlapping bars without
   bending past the farther bar's right edge. They
   connect bars within an activity;
   PowerPoint shows an arrow when both bars are on the same slide. The optional
   inclusive bounds accept whole fiscal years, such as ``FY26`` through
   ``FY27``, or exact periods, such as ``M1Q1FY26`` through ``M3Q2FY27``.
   Fiscal years expand to their first or last month. Tasks outside the range
   are omitted, and overlapping bars are clipped. Without bounds, the axis
   covers the configured fiscal year range exactly. If no fiscal years are
   configured, it covers task and completion dates. A supplied bound overrides
   that end of the default axis.

``completion [bash|zsh|fish]``
   Print a shell completion script.

   All three shells add ``.yaml`` and ``.yml`` plan input suggestions from
   ``TUXFAN_PLANNER_DATA_DIRECTORY`` alongside local filenames. Suggestions use
   relative names and support spaces and nested directory navigation. The
   directory setting is read each time; no plan is loaded or validated.
   Unset, missing, or unreadable directories add no suggestions. Absolute paths
   use normal local completion.

   Data-directory candidates appear only at plan input positions, including the
   first argument to ``merge`` and ``split``. Output paths, export-options paths,
   personal dictionaries, option values, and fields after the input retain normal
   completion behavior. When ``TUXFAN_PLANNER_DATAFILE`` supplies the input for
   ``export``, ``export-gantt``, or ``composite``, their first filename is treated
   as an output, so data-directory candidates are not added there.

``completion install``
   Configure completion on virtual environment activation for Bash, Zsh, and Fish.
   Run using the environment's Planner, then reactivate it. Existing activation
   scripts receive managed hooks and numbered backups; repeated installation
   updates hooks without duplicating them. Zsh initializes its completion system
   if needed. Shell startup files are unchanged. Reinstall hooks if the environment
   is recreated. Completion definitions remain after deactivation. CMake's
   ``install-editable`` target performs this setup automatically.
   After a planner update, reactivate the environment or reload the generated
   script to refresh rules already loaded in the current shell. The installer
   updates activation hooks; it cannot change its parent shell's loaded rules.

Object List Views
-----------------

Use ``list [task_file]`` for the full terminal planning document.
``list KIND [task_file] [FIELD ...]`` selects scoped objects. Each kind uses
its own schema fields; shared names such as status or label refer only to the
requested objects. Identity headings are retained when selecting fields.

* ``portfolios``, ``project``, ``managers``, ``pocs``, ``summary``, ``background``,
  ``fiscal_range_begin``, ``fiscal_range_end``, ``fiscal_years``,
  ``fiscal_current``, ``planned_value``, calculated ``actual_value`` and
  ``potential_value``,
  ``dependencies``, ``stakeholders``, ``users``, ``risks``: display the
  selected metadata field, with None for absent values. Preserve ordered lists
  and normalize fiscal years. Each accepts its own name as a field/filter target.
* ``execution``: ``description`` and ``activities``, including empty activities.
  Relationship filters select the execution element as a whole.
* ``tasks``: task input fields. Without fields, preserve the activity-grouped,
  numbered task layout and selected-task funding totals.
* ``milestones``: milestone fields plus ``tasks`` (historically associated),
  ``direct_tasks``, ``producer_tasks`` (required through outputs), and
  ``required_tasks`` (current direct/output requirements).
* ``deliverables``: deliverable fields plus ``producers``, ``ready``, ``required_by``.
  Default output distinguishes actual, inferred, deferred, withdrawn, blocked,
  and awaiting-acceptance states.
* ``activities``: section fields plus ``tasks``, ``task_count``, ``funding``. All
  declared activities are included even when empty; Unassigned appears when tasks
  have no section. Funding uses configured years, including zero totals, or
  infers years from funding. Multipart parent budgets count once per activity.
* ``workitems``: workitem fields plus ``tasks`` and derived ``type`` (workitem/mr). Deduplicate by ID, merging owners
  for identical metadata. Conflicting metadata stays in owner-labeled variants.
* ``risks``: risk fields plus ``tasks``. Keep each entry with its owning task.
* ``plan``: plan metadata, execution description and activity narratives, and concise
  task/milestone/deliverable relationship summaries.

For example::

   planner list tasks data/tasks.yaml --only status=planning
   planner list deliverables data/tasks.yaml label status ready required_by
   planner list deliverables data/tasks.yaml --only type=document
   planner list milestones data/tasks.yaml --only deliverables=NEEDS
   planner list activities data/tasks.yaml label task_count funding
   planner list workitems data/tasks.yaml --only status=open
   planner list risks data/tasks.yaml --only level=high
   planner list plan data/tasks.yaml

Object views filter the requested objects rather than selecting tasks first.
Every kind accepts native field targets and related tasks, activities,
tags, milestones, deliverables, and workitems. Relationship values match IDs or
labels (workitems match IDs). Singular relationship aliases work; producer and
producers alias tasks. ``TARGET=VALUE`` matches exact values;
``TARGET~VALUE`` matches literal substrings within that target. Bare values match
substrings across searchable fields. Matching ignores case, and whitespace is
trimmed. Values within one flag are OR
alternatives; repeated flags are AND requirements. Unknown fields or targets are
usage errors. Scoped derived view fields do not extend the plan input schema.

For example::

   planner list tasks data/tasks.yaml --only 'id~HARD'
   planner list tasks data/tasks.yaml --only 'id~HARD,SOFT' --only status=active
   planner list deliverables data/tasks.yaml --only 'label~report'

``id~HARD`` matches ``HARD_DEVELOPMENT``, ``HARD_SUPPORT``, and
``SOFTWARE_HARDENING``. Matching is literal, without regex or glob syntax. The
first ``=`` or ``~`` separates target and value; later operators are literal
characters in the value. ``=~`` is not a separate operator: ``label=~draft``
matches the exact label ``~draft``. Substring target selectors apply only to
explicit ``list KIND`` commands; legacy ``list`` and ``list-detail`` selectors
remain unchanged.

Task ``id=`` filters compare against both expanded task IDs and their multipart
parent IDs. ``--only id=ASSEMBLY`` selects all parts of that parent, while
``--only id=ASSEMBLY_A`` selects only the exact expanded task. Standalone IDs
remain exact matches. Exact matching ignores case and trims whitespace, without
matching prefixes or local part IDs. ``id~TEXT`` searches expanded and parent IDs
for substrings. Parent selectors combine normally with
comma alternatives and repeated filters; selectors continue to use expanded child IDs.
Default task output retains full-plan numbering and counts parent funding once.
This applies to explicit ``list tasks``; the legacy shorthand's selectors are
unchanged.

Unreferenced definitions and empty activities remain visible unless filtered.
Computations use the full plan before filtering; selecting one producer does
not change shared-output readiness. Shared workitem filters must match within
one metadata variant; selected IDs retain all variants so conflicts stay visible.
Output shares terminal Markdown, links, wrapping, colors, NO_COLOR, and paging
with task lists. IDs in identity headings and reference fields use bold standard magenta;
closed task entries retain bold gray IDs and unfunded task entries use bold muted amber IDs. This also applies to
legacy field projections, multipart parent IDs, and workitem ID fallback labels.
Ordinary prose is not highlighted merely for mentioning an ID. Wrapping uses
visible text, so ID highlighting does not change line widths. Color controls and
redirection behave as usual. Bash/zsh/fish completion includes kinds and scoped fields.

Multipart references in task relationship lists use ``parent:child``, for
example, ``Baseline Design [AIRFRAME:BASELINE]``. Milestone task lists,
deliverable producers, activity tasks, workitem owners (including metadata
variant headings), risks, and plan task summaries share this display format.
Underscores inside either ID are preserved. Task labels in relationship lists
use normal cyan. YAML IDs, dependency references, and selectors retain the
expanded ``AIRFRAME_BASELINE`` form; colon references are not selector aliases.
Normal grouped task headings continue to show source part IDs below the parent.

In ``list plan``, activities appear in declaration order with numbered
label headings (``1: Section label``), followed by indented ``ID:`` and
``Description:`` lines. This also applies to ``list plan ... execution``.

Task relationship fields display a heading followed by one indented, hyphen-bulleted task per
line, including when explicitly selecting fields. This applies to ``tasks``,
``direct_tasks``, ``producer_tasks``, ``required_tasks``, and ``producers`` in
all object views. Each reference wraps independently at the configured width (80 visible columns by default);
empty lists display ``None``. For example:

.. code-block:: text

   Tasks:
     - Baseline Design [AIRFRAME:BASELINE]
     - Advanced Design [AIRFRAME:ADVANCED]

Legacy ``list [task_file] FIELD ...`` retains cross-context projections and its
existing task selectors. With a default input, ``list deliverables`` now selects
the definition view; use ``list plan.yaml deliverables`` for the old projection.
A filename equal to a kind can be qualified, for example ``./tasks``.

Filtering List Output with ``--only``
---------------------------------------------

Legacy ``list`` and ``list-detail`` accept ``--only [TARGET=]VALUE,...``. Quote
values containing spaces::

   planner list tasks.yaml --only tags="Tag1, Tag2"
   planner list-detail tasks.yaml --only milestones="Flight Deliverables"
   planner list tasks.yaml --only milestones=FLIGHT_DELIVERABLE
   planner list tasks.yaml --only activities=Aircraft --only tags=gpu
   planner list tasks.yaml label --only tags=gpu
   planner list tasks.yaml --only "aircraft, gpu"

Targeted Matching
~~~~~~~~~~~~~~~~~~~~~~~~

A ``target=`` prefix restricts matching to one field. Targeted values match
complete values and ignore case:

* ``activities``: activity names, generated labels such as ``Activity B``, or
  activity IDs.
* ``activities``: activity IDs and labels; native task ``activity`` selects an ID.
* ``tags``: task tags only.
* ``milestones``: milestone IDs or their display labels, including indirect links through outputs.
* ``deliverables``: output IDs or display labels; matches their producing tasks.

Singular aliases (``activity``, ``activity``, ``tag``, ``milestone``)
also work. For example, ``tags=gpu`` matches the tag ``GPU``, but does not match
``gpu-kernels`` or a milestone named ``GPU``. Milestone matching includes
references inherited by multipart parts.

Bare Text and Combining Filters
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Without a target prefix, values match substrings across all the fields above.
For example, ``--only "aircraft"`` can match a milestone ID containing ``AIRCRAFT``,
an activity named ``Flight Development``, or a task tag containing ``aircraft``.
These matches ignore case and trim surrounding whitespace; they use literal
text rather than regular expressions or wildcards.

Values separated by commas within one ``--only`` are alternatives: any value
may match. Repeating ``--only`` narrows the result: **all flags must match**.
For example, ``--only activities=Aircraft --only tags="gpu, checkpoint"`` requires
the Aircraft section and either the gpu tag or the checkpoint tag. Bare and
targeted flags can be combined, such as ``--only aircraft --only tags=gpu``.
Unknown targets and empty value lists are usage errors.

Only matching tasks and their associated activities appear. With ``list --only``,
activity headings show only IDs and labels, omitting activity descriptions.
Activity letters,
task numbers, and dependency references retain their full-plan values.
Referenced dependencies are not automatically included. ``list-detail`` also
limits activity and milestone metadata to the selected tasks.
Omitting ``--only`` displays all tasks. An empty selector list is a usage error;
unmatched selectors produce a no-matches message and zero totals for configured
years, except that field selection omits totals. This option applies to the two
list commands, not exports.

Selecting Fields in Legacy List Output
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

In ``list FIELD``, replace ``FIELD`` with any supported canonical input field
identifier. Use its exact spelling, including underscores. For example:

.. code-block:: bash

   planner list plan.yaml label
   planner list plan.yaml status assignees --only tags=gpu
   planner list plan.yaml mitigation --only activities=Solver
   planner list plan.yaml workitems
   planner list plan.yaml activity funding

Names combine their selections; repeating a name has no additional effect.
Without field names, ordinary ``list`` behavior is unchanged. These selections
are available only on ``list``, not ``list-detail`` or exports.

Supported fields are grouped below by their source. Shared names are written
only once on the command line and select all applicable levels:

.. list-table:: Field names
   :header-rows: 1
   :widths: 20 80

   * - Source
     - Fields
   * - Plan
     - ``portfolios``, ``project``, ``managers``, ``pocs``, ``summary``,
       ``fiscal_range_begin``, ``fiscal_range_end``, ``fiscal_years``,
       ``milestones``, ``deliverables``, ``execution``, ``tasks``
   * - Task
     - ``id``, ``label``, ``activity``,
       ``description``, ``note``, ``site``, ``bnr``, ``funding``,
       ``type``, ``tags``, ``start``, ``end``, ``expected``, ``completed``,
       ``priority``, ``status``, ``dependencies``, ``funding``,
       ``milestones``, ``deliverables``, ``risk``, ``workitems``
   * - Work item
     - ``id``, ``label``, ``description``, ``status``, ``assignees``
   * - Risk
     - ``type``, ``level``, ``description``, ``mitigation``
   * - Deliverable definition
     - ``id``, ``label``, ``description``, ``type``, ``status``, ``completed``
   * - Milestone definition
     - ``id``, ``label``, ``description``, ``deadline``, ``deliverables``
   * - Execution narrative
     - ``description``, ``activities``
   * - Activity
     - ``id``, ``label``, ``description``

Names retain input spelling, including underscores: use ``activity``,
not ``--activity``. Abbreviations, input aliases, computed fields such
as ``--end``, internal names such as ``--risks``, and arbitrary metadata keys
are not accepted. Composition directives such as ``defaults`` and ``parts``
are applied during loading and are not selectable model fields. The former
``--labels`` flag is removed; use ``label``.

Context for nested fields
^^^^^^^^^^^^^^^^^^^^^^^^^

A nested selection includes the activity, task, and item identity needed to
interpret the value. For example, ``assignees`` can display:

.. code-block:: text

   Solver Development [solver]
     Task: Update solver [SOLVER_UPDATE]
       Work item: GPU memory management [aircraft/design#42]
         Assignees: designer_one, designer_two

``mitigation`` identifies the risk by type and level beneath its task before
showing mitigation text. ``status`` shows both task and work item statuses.
``description`` selects task, activity, risk, work item, and milestone
narratives. ``type`` selects task/risk types; a work item's inferred type
is not an input field and is not selected.

A container name such as ``risk`` or ``workitems`` displays its full
contents. Combining it with a child name does not duplicate that branch.
``tasks`` displays all fields of selected, expanded tasks. ``milestones``
also shows top-level milestone definitions and task milestone references.
``execution``, ``activities``, and ``description`` access the separate
execution narrative; ordinary activity context uses task grouping as before.

Fields are rendered in schema order, with activity/task ordering preserved and
work items in input order. Identity fields already present in headings are not
repeated. Missing or empty requested values display ``None``. Branches without
any requested field are omitted; if none apply, output is
``No selected fields are present.`` Long values wrap at the configured width (80 by default).
Inline Markdown and color controls apply, with unfunded task branches muted amber.
Explicit ``--color always`` overrides automatic detection, including ``NO_COLOR``.

Compact label outline
^^^^^^^^^^^^^^^^^^^^^

``label`` alone retains the compact activity/task/work item outline:

.. code-block:: text

   Solver Development
     Update solver
       GPU memory management
       aircraft/design!69
     Validate solver

Tasks are indented two spaces and work items four. Work items without labels
use their IDs. This compact form omits plan/milestone metadata, generated
numbers, and field prefixes. Adding other field names uses the contextual
format described above. An empty plan without filters produces an empty
label outline.

Filtering and omitted output
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

``--only`` selects tasks first. Each selected task retains its work items;
only activities containing selected tasks appear. Milestone definitions and
explicitly selected activities are limited to those referenced by
selected tasks. Without filters, all plan-level definitions remain available.
The supported selector fields do not change: task labels and work item
labels/IDs are not additional search fields. A targeted filter can still use
``activities=Activity B`` even though field-selected output omits numbering.
Repeated filters remain AND requirements, with OR alternatives within a flag.

Field-selected output omits unrelated fields, separator rules, generated
numbering, and funding totals. An unmatched filter prints only
``No tasks match --only.``

Funding Totals for Filtered Lists
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Fiscal-year totals use the selected tasks:

* A standalone task contributes its own funding.
* If a multipart parent specifies funding, its full budget contributes once
  when any of its parts match. It is not prorated, counted repeatedly, or added
  to part-level amounts, even if matching parts override funding.
* Without parent funding, only matching parts contribute their own amounts.

For example, a parent with ``FY27: 300K`` contributes ``300K`` whether one or
several parts match. Without that parent budget, matching parts with ``100K``
and ``50K`` contribute ``150K``. Every configured fiscal year remains in totals,
including zero-funded years. Individual task funding lines continue to show
the task's explicit or inherited funding. These funding lines and totals are
omitted whenever ``list`` field names are supplied.

Run ``planner list --help`` or ``planner list-detail --help`` for command-line
examples and a description of the matching and funding rules.

Environment Variables
---------------------

``TUXFAN_PLANNER_RATES_FILE``
   Overrides configuration ``rates_file`` for staff-funded labor. Relative paths
   use the working directory; an empty value leaves configuration active. Rates
   load only when staff allocations need them. See :doc:`funding`.


``TUXFAN_PLANNER_DATAFILE``
   Default plan file. When set, basic commands can omit ``task_file`` and export
   commands and ``composite`` can pass only the output path.
   An empty value behaves as unset: an explicit input filename is required,
   and output-only commands do not infer an input. Missing input produces a
   normal usage error (exit status 2).

``TUXFAN_PLANNER_PAGER``
   Optional pager executable and arguments for long interactive output, such as
   ``less -R``. Unset/empty values disable paging. This does not choose a data
   file or affect exported files. See the paging behavior above.

``TUXFAN_PLANNER_EDITOR`` / ``EDITOR``
   Editor executable and arguments for ``add`` and ``edit``. The planner-specific setting
   takes precedence; unset, empty or whitespace-only values fall back to
   ``EDITOR``. At least one usable setting is required. Quoted paths and
   arguments are parsed without a shell. GUI editors must wait for the buffer
   to close, for example ``code --wait``.

``TUXFAN_PLANNER_DATA_DIRECTORY``
   Directory used for every relative plan filename, including the default from
   ``TUXFAN_PLANNER_DATAFILE``. It takes precedence over the current directory;
   if the file is missing there, the same relative filename is tried in the
   current directory. Existing invalid or unreadable inputs do not trigger fallback.
   The configured path must be an existing directory when resolving a relative
   input. Absolute inputs bypass it, and an empty value behaves as unset.
   Home-directory notation (``~``) is expanded. Setting only the directory does
   not choose a default file: pass a filename or also set the data-file variable.
   The setting applies to read, edit, export, composite, format, spell-check, merge,
   and split inputs.
   Output and export-options paths retain their current-directory semantics;
   ``!include`` paths retain containing-file semantics.

   .. code-block:: bash

      export TUXFAN_PLANNER_DATA_DIRECTORY="$PWD/data"
      # Planner initializes the default user configuration automatically on first use.
      planner validate tasks.yaml
      planner list composite.yaml label
      planner export tasks.yaml /tmp/airplane.docx
      export TUXFAN_PLANNER_DATAFILE=tasks.yaml
      planner validate

   This checkout provides fictional jet-airplane development fixtures under
   ``data/``; see :doc:`development-data`.

``TUXFAN_PLANNER_TEMPLATE_DIRECTORY``
   First directory searched for ``template.pptx`` or ``template.potx`` by
   PowerPoint plan export. An empty value is unset; ``~`` is expanded and
   relative paths resolve from the current directory. The directory must exist.
   The current directory is searched next, then the built-in design is used.
   This setting does not affect ``export-gantt`` or other formats.

``XDG_CONFIG_HOME``
   Absolute base directory for user configuration; defaults to ``~/.config``.
   See :doc:`configuration` for initialization, validation, and migration.

The help and usage messages show whether each planner environment variable is
set and display its current value when set. Run ``planner --help`` to check
them. On compatible terminals, variable names are bold and only the displayed
value (including quotes) is green when set. Purpose text, ``set to``, and
``not set`` remain plain. Wrapped values retain their color; explicitly empty
values display green ``''``. Redirection, ``NO_COLOR``, and ``TERM=dumb`` disable
these styles. Empty-value resolution rules remain as documented above.
Ill-formed commands print an error and the relevant command help to
stderr, then exit with status 2.

Exit Status
-----------

* ``0``: the command completed successfully. Validation warnings do not make a
  valid plan fail.
* ``1``: validation or another command operation failed. Diagnostics go to stderr.
* ``2``: command-line arguments are invalid or required arguments are missing.

Examples
--------

.. code-block:: bash

   planner validate planner/examples/tasks.yaml
   planner list planner/examples/tasks.yaml
   planner list planner/examples/tasks.yaml label
   planner list planner/examples/tasks.yaml status mitigation
   planner list planner/examples/tasks.yaml label --only activities="Planning System"
   planner list-detail planner/examples/tasks.yaml
   planner list planner/examples/tasks.yaml --only "architecture"
   planner list-detail planner/examples/tasks.yaml --only "Design"
   planner schedule planner/examples/tasks.yaml
   planner composite planner/examples/tasks.yaml /tmp/expanded.yaml
   # Planner initializes the default user configuration automatically on first use.
   planner validate /tmp/expanded.yaml
   planner export planner/examples/tasks.yaml /tmp/plan.docx
   planner export planner/examples/tasks.yaml /tmp/plan.svg
   planner export-gantt planner/examples/tasks.yaml /tmp/gantt.svg
   planner export-gantt planner/examples/tasks.yaml /tmp/gantt.pptx
   planner export-gantt planner/examples/tasks.yaml /tmp/fy26-fy27.svg --from FY26 --through FY27
   planner export-gantt planner/examples/tasks.yaml /tmp/partial.pptx --from M1Q1FY26 --through M3Q2FY27

With default input and export options:

.. code-block:: bash

   export TUXFAN_PLANNER_DATAFILE=planner/examples/tasks.yaml
   # Planner initializes the default user configuration automatically on first use.
   planner validate
   planner list label
   planner composite /tmp/expanded.yaml
   planner export /tmp/plan.docx

Input Integrity
---------------

Task IDs, labels, and descriptions must be non-empty strings. Execution-section
links are optional; all unlinked tasks appear under Unassigned.
Use quoted strings for numeric IDs. YAML plan and export-option files reject
duplicate explicit keys with a source filename and line number; explicit
values may still override values inherited through YAML merge keys (``<<``).

Only documented fields are accepted in every input mapping. Unknown fields
raise generic errors regardless of whether the name was supported previously.
Funding is the sole budget input; the optional Word Funding column shows a
computed task total. Filters support activities, tags, and milestones.

Deliverable inspection
----------------------

``fields deliverable`` prints the output schema; ``avail deliverables.type``
prints ``paper``, ``document``, ``presentation``, ``release``, ``software``,
``dataset``, ``model``, ``service``, ``training``, ``demonstration``, ``assessment``,
``design``, and ``hardware``. ``show FILE deliverables.type``
collects types used in a plan. ``list FILE deliverables`` selects definitions
and references. ``list-detail`` and ``summary`` show readiness, required-by dates,
and producers; ``schedule`` shows task references and required-by dates.
``validate`` counts deliverable definitions and warns about missed milestone
deadlines, unknown required timing, and required outputs without producers.
See :doc:`schema` for the all-producers rule and legacy prose migration.

Deliverable status defaults to ``required``. ``planning`` defers assessment,
``closed`` removes the requirement, and explicit ``complete`` fulfills it without
requiring producer completion. Direct task requirements remain. References retain
non-default status annotations, and detail/summary/plan exports distinguish deferred,
no-longer-required, complete-with-unknown-date, and inferred-complete outputs.
Optional ``completed`` requires ``status: complete`` and records an actual fiscal
period for historical deadline checking. ``show FILE deliverables.status`` and
``avail deliverables.status`` inspect stored states and allowed choices; templates
comment out ``completed`` because the default status is required. Historical
relationship filters and summary counts remain available for every status.

``blocked`` outputs remain required with an obstacle. ``submitted`` outputs are
awaiting acceptance and remain outstanding. Both retain producer/deadline checks,
including missing or undated producers. Completed producers do not implicitly
unblock or accept these outputs. Detail/summary and Word/SVG output label those
states explicitly; references annotate them as ``[blocked]`` or ``[submitted]``.
Both are available in templates, ``show FILE deliverables.status``, and
``avail deliverables.status``. ``completed`` remains exclusive to complete outputs.

The ``document`` deliverable type describes material that does not require
submission, such as internal documentation. It may be marked ``complete``
directly. ``paper`` describes a paper intended for submission.

General Configuration
---------------------

``planner config init [--config PATH]`` creates a complete user configuration
from the packaged default without overwriting any existing file. The default is
``~/.config/tuxfan-planner/config.yaml`` (honoring ``XDG_CONFIG_HOME``). A missing
implicit default is initialized automatically on first operational use.

``--config PATH`` is accepted before or after every command, including scoped
``list`` commands. Explicit missing files and existing invalid/unreadable files
fail with exit status 1. Configuration is YAML and contains ``config_version``,
``task_priorities``, ``task_categories``, and ``export``. Optional ``sites``
and ``bnrs`` are ID-only allowlists. Tasks accept one site and one
B&R ID; ``type`` accepts one built-in ID or a list of IDs:
``labor``, ``contract``, ``equipment``, ``services``, ``nonlabor``. The former configuration
``types`` section is rejected; remove it from existing configurations.
Omitted site/bnr sections leave those fields unrestricted; empty lists permit only
empty task values. Exports display these IDs. ``avail site`` and ``avail bnr``
display configured choices; ``avail type`` displays the built-in types. The old
``--export-options`` argument is removed and its environment variable is ignored.

Tasks optionally specify one scalar ``priority`` ID from ``task_priorities``.
Omitted/null/empty text means unassigned; IDs are trimmed and matched exactly.
Defaults and parts inherit, replace, or clear the value. Lists and unknown IDs
are rejected. ``list tasks FILE priority`` and ``--only priority=capability``
operate on task assignments. ``avail priority`` lists configured IDs and
``show tasks.priority`` lists used IDs. Category remains a required single ID.
There is no project priority element or calculated primary priority.
Terminal task displays use configured category and priority labels, including
explicit field projections, configured lines, ``list-detail``, and ``schedule``.
List views and ``list-detail`` append the canonical ID in brackets, for example
``Essential delivery [DELIVER]``. The bracketed suffix uses light cyan (ANSI 96)
when colors are enabled, including configured lines and explicit projections.
Missing priorities and mixed parent summaries retain None/Mixed without IDs.
Export task narratives use configured labels. Word/PDF task tables use optional
``table_entry`` values from ``task_categories`` and ``task_priorities``, falling
back to canonical IDs unchanged. No automatic CAT/ASC conversion is applied.
``avail category`` and ``avail priority`` also show explicit table labels.
This is presentation only: plans, validation, filters, ``show``, ``avail``,
and templates continue to use canonical IDs. Word import resolves the display
labels or explicit table values back to configured IDs. Table IDs disambiguate
duplicate priority labels; without enough information, import requires review.
See :doc:`configuration` for the full file format and migration instructions.

Default Full-Plan Listing
-------------------------

Unqualified ``list FILE`` and default-input ``list`` render every plan element,
independently of ``export.elements`` and ``export.layout``.
Notes present in source are shown. Existing field projections, including
``list FILE summary tasks``, keep their established behavior.

Unqualified ``--only`` retains task-filter matching. It restricts task narratives
and related activities/milestone/deliverable definitions; metadata,
readiness, and references retain full-plan context. No matches retains the
existing notice and zero funding totals. Use explicit kinds for native object
filters. Full output uses the standard color/Markdown/wrapping/paging behavior.

Project-Year Funding
--------------------

Plans may declare ``fiscal_current: FY27`` and ``planned_value: $100K``. The year is
explicit, independent of today's date and fiscal coverage. A planned value
requires a current year; amounts use funding syntax and display in dollar-prefixed
thousands. ``actual_value`` is read-only current-year funded task funding across the
full plan: every status except ``unfunded``, with authoritative parent budgets once.
``potential_value`` adds unfunded tasks and is never budget-colored. Both measure
allocations, not expenditures. It remains a complete-project total
in filtered list output. Missing fiscal_current means unavailable; missing yearly funding
means zero; missing planned value means a neutral comparison.

Use ``planner list fiscal_current plan.yaml``, ``planner list planned_value plan.yaml``,
``planner list actual_value plan.yaml``, ``planner list potential_value plan.yaml``, or
``planner show plan.yaml actual_value``. Metadata and legacy projections also accept
these names; ``show`` remains plain text.
List Actual Value amounts are green below plan, black at plan and red above plan,
subject to ``--color``, redirection and ``NO_COLOR``. Configured ``list.elements``
and ``export.elements`` accept each name independently, including per-standard
export rules. ``actual_value`` and ``potential_value`` are rejected in authored plans
and recomputed on Word import; ``planner fields plan`` shows the two inputs and
``fields config`` shows the output selectors.

Configured List Presentation
----------------------------

An optional general-configuration ``list.elements`` tree controls terminal
selection, ordering and styled repeated lines independently of exports. Without
it the existing list layouts are retained. Explicit kinds request their scope
even when configuration omits it; explicit positional fields use the existing
projection and override configured selection/layout. ``--only`` still filters
objects using the complete plan.

Ordered task, milestone, and deliverable instructions use the same boolean
``heading`` controls as exports, including line defaults and per-field overrides.
Omitting the setting retains the existing terminal field labels.

Configured lists may add a ``totals`` element: plan-wide funding totals,
printed at the element's position in ``list.elements`` like any other element.
A bare ``totals:`` prints ``Funded Total``. Its optional ``activity`` and
``bnr`` children add, in order, each activity's B&R rows and activity total,
then the plan-wide B&R rows, before ``Funded Total``. Regular totals always
exclude unfunded budgets. The ``unfunded`` child adds a separate
``Unfunded Total:`` immediately before ``Funded Total:`` using the same
formatting as the other subtotals (``planner list totals FILE unfunded``).
This replaces its previous behavior of including unfunded amounts in totals.

Totals print as a table: one row of fiscal years, then a two-line pair per
total, with its bold magenta label and trailing colon on the first line and its green amounts on the second,
left-aligned under their years in equal eight-character columns, separated by
three spaces. The grid sits at the right edge: the widest final-column year
or amount ends at the delimiter, without trailing spaces. The ``Activity A`` portion uses cyan record-title coloring. A rule sets ``Funded Total`` apart from the
subtotals. B&R labels use ``Activity A B&R CODE Total:`` within activities
and ``B&R CODE Total:`` for plan-wide totals. When the years do not fit in
the configured width (80 columns by default), the table repeats in
consecutive blocks of years::

   ════════════════════════════════════════════════════════════════════════════
   Totals:
   ════════════════════════════════════════════════════════════════════════════
                                                    FY27       FY28       FY29
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
     Activity A Total:
                                                    $260K      $260K      $260K
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
     Funded Total:
                                                    $4945K     $2710K     $360K

Configuration example::

   list:
     elements:
       project:
       tasks:
         - line: [label, id, status]
         - description:
       totals:
         activity:
         bnr:
       deliverables:

Totals cover the tasks the list shows, so ``--only`` filters them. Declaring
``totals`` replaces the ``Funded Total:`` line that a bare ``tasks`` element
prints; without it, that line is unchanged and custom task layouts print no
total. ``totals`` is computed, not a plan field, and is not an export element
(export tables use ``task_table.totals`` with the same ``activity``, ``bnr``, and
``unfunded`` children; table ``activity`` also accepts ``top`` or ``bottom``).
Bare/true table totals shows only the overall total; false or an empty mapping
disables it. Legacy table siblings ``totals_activity``, ``totals_bnr``, and
``totals_unfunded`` remain supported with boolean/bare totals, but cannot be
mixed with a totals mapping. Totals print one amount per plan fiscal year, so a plan
without ``fiscal_years`` (or a fiscal range) prints none.

``planner list totals FILE`` prints only the totals table, without the section
heading. Name ``activity``, ``bnr``, or ``unfunded`` to choose breakdowns, for example
``planner list totals FILE bnr``; otherwise a configured ``totals`` element's
choices apply, and the default is activity and B&R subtotals. ``--only`` takes task filter targets
and sums only the matching tasks::

   planner list totals plan.yaml
   planner list totals plan.yaml activity
   planner list totals plan.yaml bnr --only activity=WINGS

Use ``planner list plan.yaml --ignore-config`` to print complete records while
bypassing configured list presentation. Scoped kinds and explicit fields/filters
remain honored. Classification vocabularies and allowlists still load for
validation and labels. ``--config`` and ``--ignore-config`` are mutually exclusive
regardless of position; other commands reject the bypass option. Subcommand help
and bash/zsh/fish completions include it. See :doc:`configuration` for examples.

Metadata presentation
---------------------

Use ``portfolios`` (plural) in plans, list/show fields and export selections.
``portfolios``, ``managers`` and ``pocs`` accept scalar text, YAML sequences, and
literal/folded Markdown lists. ``fields config`` includes examples of
``export.layout.context_colors`` and ``list.layout.context_colors`` and the
optional ``layout.metadata`` heading/value controls. These styles do not alter
content inclusion. Explicit field selections retain the active list color
policy; ``--ignore-config`` bypasses list presentation settings.

Activity migration
------------------

``fields activity`` prints an id-first activity mapping; insert it under
``execution.activities``. ``fields execution`` prints the containing mapping.
The former ``fields section`` and ``execution.sections`` names are rejected.
``show execution.description`` and ``show execution.activities.id`` use the new
schema. Task references and selections use ``activity``.

``list activities`` displays every declared activity, including empty entries,
and a generated Unassigned group when needed. Activity letters follow complete
plan declaration order and survive task filtering. Use ``--only activities=ID``
for relationships, or task ``--only activity=ID`` for the native reference.
Configured lists support ordered formatting under ``execution.activities``;
``--ignore-config`` retains complete native output.

Execution description formatting
--------------------------------

``fields config`` shows an optional ordered execution layout for export and
configured list output. Under ``elements.execution``, use ``- description:``
with sibling ``heading: false`` to retain execution prose without its description
heading. Add ``- activities:`` to retain activity definitions. Omitted or true
heading uses the default visible description heading; the standard's top-level
Execution heading is independent. The existing mapping syntax remains valid.

Alternatively, use the concise mapping ``execution: {description: {heading:
false}, activities: null}``. The description style accepts only a boolean heading
control. ``fields config`` includes examples of both supported forms.

Scoped export spacing
---------------------

``fields config`` shows optional collection spacing settings. Under export
elements, tasks/milestones/deliverables accept ``spacing: normal`` or ``tight``
in mappings, or a standalone spacing instruction in their ordered format lists.
Execution and its description/activities, summary/background, resourcing prose
and multi-value metadata support the same override. Omission inherits the nearest
parent setting or ``export.layout.spacing``. Spacing-only entries retain default
content; explicit field exclusions remain effective. Table cell formatting and
terminal list presentation stay independent.

Generated-number headings
-------------------------

Exports and configured lists print generated task/activity heading numbers with
a colon before the following label, including multipart children and short
numbers: ``Task A.1.1: label`` or ``A.1.1: label``. A ``line: [number, label]``
instruction uses this separator automatically. Number-only table cells and
stable IDs remain unchanged. Gantt task labels follow the same convention.

Project Dependency and Risk Views
---------------------------------

``list dependencies [task_file] [FIELD ...]`` lists project commitments with
promised fiscal dates, linked project risk IDs, and referencing tasks.
``list risks [task_file] [FIELD ...]`` lists both reusable project risks and
private inline task risks. Project risks appear first; inline entries identify
their owning task. ``--only scope=project`` and ``--only scope=task`` restrict
risk ownership scope. Other native fields and task relationship filters retain
the usual matching rules. Risk headings are unnumbered and severity-colored.

``fields dependency`` (or ``fields dependencies``) prints a commitment template.
``fields project-risk`` (also ``fields risks``) prints a project risk template;
``fields risk`` continues to print a private inline task risk template.
``fields plan`` includes both structured collections. ``fields config`` includes
the new content selections and an ordered risk-format example.

``avail dependencies.type`` prints internal, external. ``avail risks.type``
prints the five project risk classifications; ``avail risk.type`` retains the
same choices for inline task risks. ``show FILE dependencies.promised`` and
``show FILE risks.id`` inspect project definitions. CLI help and shell
completions include these fields and template kinds.

``schedule`` keeps task-to-task ordering and cycle checks. A project dependency
is a commitment, not a task node. An otherwise-ready pending task with such a
reference stays BLOCKED, with its delivery shown as unconfirmed. A promised date
passing does not establish delivery. Starts before a promised month issue
source-located warnings; starts in the same month are allowed. Dates are not
rescheduled. Explicit task statuses retain their existing behavior.

The plan/configuration prose names ``request_dependencies`` and ``external_risks``
are replaced by structured ``dependencies`` and ``risks``. Legacy Word prose is
preserved in summary text with review notices; migration does not invent facts.

Parent summaries in task lists
------------------------------

``planner list tasks plan.yaml --parents`` collapses matching multipart parts
to a parent summary and retains standalone tasks. The default full-document
``planner list plan.yaml --parents`` form is also supported. Filters select
original parts before summarizing; partial selections carry a visible count.
Mixed fields and partial timing are indicated. Source tasks remain authoritative
for budgets, readiness and dependencies. Positional fields, configured list
presentation and ``--ignore-config`` support the flag. It is independent of
``export.layout.multipart`` and is rejected for non-task list kinds.

Task funding values in list output include a dollar prefix (for example,
``$50K``) and appear green when colors are enabled. This also applies to
selected funding fields and configured task lists. Closed and unfunded task
blocks retain their gray and muted amber colors.

Activity funding, including nested execution/plan activity summaries, also
uses dollar-prefixed green amounts in list output.

Nested plan organization and export placement
---------------------------------------------

``fields plan`` now emits ``execution`` with description, activities, tasks,
milestones, and deliverables, plus ``resourcing`` with project dependencies,
stakeholders, users, and risks. ``fields execution`` and ``fields resourcing``
print the corresponding containers. Flat authored plans remain readable; fields
cannot be defined in both locations, even if empty. Included collection files
remain lists: move their include directives beneath the appropriate container.
Word import writes nested plans. Merge/split preserve the input's organization.
``show`` also accepts paths such as ``execution.tasks.label`` and
``resourcing.dependencies.id``; existing object view and field names remain
available.

``export.structure`` specifies section order and execution/resourcing groups
independently of ``export.elements`` content selection. The execution group's
introductory description precedes its listed children; ``activities`` places
activity definitions. Empty/excluded sections produce no parent heading.
Word/PDF use subordinate outline levels. SVG/PowerPoint follow narrative
placement; their existing formats do not render the Word funding table.
Without structure, existing elements declaration order remains supported.
See :doc:`export-options` for the placement syntax and per-standard overrides.

Export selection containers
---------------------------

``export.elements`` now uses the same execution/resourcing containers as plan
YAML, with the generated funding table at ``resourcing.task_table``. Nested
child declaration order supplies the default export placement. ``structure``
remains an optional placement override. Flat field selections remain compatible;
a field cannot be specified in both locations, even when disabled or empty.
Task and definition instructions work within the nested children. Execution
spacing inherits to its selected children; resourcing spacing inherits to its
selected prose/definition children, with explicit child overrides taking
precedence. The task table remains independent. ``fields config`` prints the
canonical nested configuration. Existing configured terminal list selections
keep their own object scopes and are unchanged.

Word/PDF final table pagination
-------------------------------

Exports keep Word's required empty paragraph after a final task table compact,
avoiding a blank last page caused by normal body paragraph formatting. This
applies to portrait and landscape tables, including per-standard layouts and
custom body font sizes.

Priority Schema Migration
-------------------------

``migrate-priorities PATH [--config PATH] [--write]`` explicitly migrates YAML
plans or a directory of YAML plans. By default it reports changes without
writing. With ``--write``, it backs up every changed file before saving. It
renames the configuration vocabulary to ``task_priorities``, moves former
project assignments into task-list defaults, and changes export/list selections
and the old ``project_priorities`` table column to task ``priority``. Includes
and comments are retained. Singleton lists become scalar IDs. Multiple IDs,
legacy urgency values, and conflicting assignments require review before writing;
unrelated older schema errors remain for review.

Editing a plan entry
--------------------

``edit ID [task_file] [--kind KIND] [--owner TASK_ID]``
   ``planner edit config`` opens the complete active general configuration.
   ``planner config edit`` is an equivalent alias.
   ``--config PATH`` selects an alternate file. This form does not require or
   load a plan, and can repair an invalid configuration. It uses the same
   editor, retry/cancel behavior, atomic saves and numbered backups described
   below, validating the complete configuration before saving. Comments and
   formatting are preserved as edited. A missing implicit default is initialized;
   an explicitly selected missing file is an error. Symlinks are preserved by
   editing their resolved target, with backups beside that target. Concurrent
   changes to the target or a change in the selected path's resolution prevent
   saving. To select a plan entry literally named ``config``, supply its plan
   file or ``--kind``. ``--owner`` does not apply to configuration editing.

   Open one authored mapping as a temporary YAML buffer using
   ``TUXFAN_PLANNER_EDITOR``. For example::

      export TUXFAN_PLANNER_EDITOR='vim'
      planner edit BUILD_WING plan.yaml
      planner edit RELEASE_GATE --kind milestone
      planner edit 'aircraft/design#42' plan.yaml --kind workitem --owner BUILD_WING

   The file defaults to ``TUXFAN_PLANNER_DATAFILE``; relative input paths honor
   ``TUXFAN_PLANNER_DATA_DIRECTORY``. Editor commands accept quoted paths and
   arguments without a shell. A GUI editor must wait until editing finishes
   (for example, ``code --wait``). If that variable is unset or empty, planner uses ``EDITOR``.
   Set at least one of these variables to a usable editor command. Editor failures retain the buffer and leave plan files alone.

   Kinds are ``task``, ``activity``, ``milestone``, ``deliverable``, ``dependency``,
   ``project-risk``, and ``workitem``. Matching uses exact, case-sensitive IDs.
   Multipart parents and parts are editable; use an expanded ID for a part.
   The buffer retains authored inheritance rather than inserting effective
   defaults. IDs shared across kinds require ``--kind``; repeated work-item
   references require their authored task's ID in ``--owner``. ID-less prose,
   defaults and private task risks have no ID selector. The selected ID must
   remain unchanged; use ``rename`` to change an ID and its semantic references.

   Planner validates the complete plan with the replacement in memory before
   saving, using the active configuration and normal warning/error rules.
   Unrelated validation errors also prevent saving. Invalid buffers can be
   reopened or cancelled; cancellation, validation failure, editor failure and
   write failure retain the edited buffer at the printed path. An unchanged
   buffer exits without saving or creating a backup.

   A successful edit replaces only the selected authored entry, in its original
   included file when applicable, with a numbered backup and atomic save.
   Other source text remains unchanged. Concurrent changes to any loaded plan
   source prevent saving. YAML anchors, aliases and merge mappings within the
   selected entry are unsupported. Python plans support uniquely located
   literal dictionaries, converted back from the YAML editing buffer; computed
   entries are rejected before launching the editor. Normal Python plan loading
   executes the plan, including when validating a replacement.

Renaming IDs and references
---------------------------

``rename OLD_ID NEW_ID [task_file] [--kind KIND] [--owner TASK_ID] [--write]``
   Preview a validated ID rename and its semantic reference updates. ``--write``
   applies the prepared changes with numbered backups without prompting.
   Otherwise, when both input and output are terminals, the preview ends with
   ``Apply this rename? [y/N]:``. Only ``y`` or ``yes`` (case-insensitive) writes;
   Enter, other responses and end-of-input decline. Ctrl-C cancels with exit
   status 130. With redirected/noninteractive input or output, it remains a
   preview unless ``--write`` is supplied. Omit the file to use
   ``TUXFAN_PLANNER_DATAFILE``; relative inputs honor
   ``TUXFAN_PLANNER_DATA_DIRECTORY``. ``--config`` selects normal validation
   vocabularies. No editor or editor environment variable is required.

   .. code-block:: bash

      planner rename BUILD_WING DESIGN_WING plan.yaml
      planner rename BUILD_WING DESIGN_WING plan.yaml --write
      planner rename RELEASE_GATE FINAL_GATE --kind milestone --write
      planner rename PARENT_A C plan.yaml --kind task --write

   Selection follows ``edit``: exact case-sensitive IDs across task, activity,
   milestone, deliverable, dependency, project-risk and workitem kinds. Use
   ``--kind`` for overlapping namespaces and ``--owner`` for repeated work-item
   references. Work-item renaming changes the selected authored reference only;
   no server object or other owner's reference is changed.

   .. list-table:: Reference updates
      :header-rows: 1

      * - Renamed kind
        - Authored reference fields updated
      * - Task or multipart part
        - Task dependencies, including sibling aliases and expanded IDs
      * - Activity
        - Task activity
      * - Milestone
        - Task milestones
      * - Deliverable
        - Task deliverables and milestone deliverables
      * - Project dependency
        - Task dependencies
      * - Project risk
        - Project dependency risks
      * - Work item
        - Selected owner's work-item ID; there are no inbound plan references

   A parent rename updates the parent's alias and every expanded part ID. Parts
   authored with an explicit parent prefix are updated too. For a part, NEW_ID
   can be local or expanded; its local/prefixed authoring style is retained.
   Collisions are checked in the corresponding namespace, and full-plan
   validation checks cross-namespace constraints. The resolved dependency graph
   must retain the same relationships after applying the ID substitutions;
   ambiguous alias capture is rejected rather than silently redirecting edges.

   Scope is the loaded plan and recursive includes. Other independent plans and
   configuration vocabulary IDs are not searched. Scalar source edits preserve
   surrounding formatting, comments, and quoting. Prose and labels containing
   old IDs remain literal. Affected YAML anchors, aliases or merged fields and
   computed Python entries/references must first be made explicit; literal
   Python IDs/references are supported without rewriting other code. Unchanged
   IDs exit without backups or prompts. An unconfirmed preview writes no plan
   source or backup files. Sources are checked again after confirmation so
   changes made while the prompt is open prevent saving.

   Before saving, planner validates all replacement sources together and checks
   every input snapshot for concurrent changes. Each file is saved atomically
   with a numbered backup. A handled write failure restores already written
   files when they still contain the prepared replacement. A concurrent change
   prevents rollback from overwriting that file; errors identify manual recovery
   needs and retained backups. A forced termination can also require recovery
   from backups: there is no filesystem-wide atomic transaction across files.

Adding entries
--------------

``add TYPE [task_file] [--parent TASK_ID] [--owner TASK_ID] [--destination PATH]``
   Open a YAML mapping template in ``TUXFAN_PLANNER_EDITOR`` or, if unset/empty,
   ``EDITOR``. GUI editors need a wait option. TYPE is ``task``, ``activity``,
   ``milestone``, ``deliverable``, ``dependency``, ``project-risk``, or ``workitem``.
   Templates use the same schema and active vocabulary examples as ``fields``;
   optional task risk/work-item examples are commented out. For example::

      planner add task plan.yaml
      planner add milestone plan.yaml --destination milestones.yaml
      planner add task plan.yaml --parent BUILD_WING
      planner add workitem plan.yaml --owner BUILD_WING

   ``--parent`` requires an existing multipart parent; nested parts are not
   supported. Part templates retain inheritance and include missing required
   fields when needed. Work items require ``--owner``. Adding to a part with
   inherited references creates an override retaining the existing references.
   Duplicate IDs in the selected namespace are rejected. The editor buffer
   must contain exactly one mapping. An unchanged template cancels; invalid
   additions can be reopened or cancelled. Editor, validation or save failures
   retain the buffer at its printed recovery path. Valid entries save on editor
   exit, following full-plan validation; no additional confirmation is needed.

   Composite plans offer a numbered destination menu scoped to the selected
   collection and owner. Choices may include the root plan, included lists,
   single-entry includes (converted into lists), or creation of a new included
   YAML file. ``--destination`` selects an existing compatible file or a new
   filename without the menu. Relative destinations use the root plan directory.
   New filenames require an existing directory and a ``.yaml`` or ``.yml`` suffix;
   existing unrelated files and input sources cannot be overwritten. A
   noninteractive/redirected composite addition requires an explicit destination. Empty
   input cancels destination selection. Raw task-list plans accept tasks only;
   adding other definition types requires a mapping plan.

   New files and their include directives are validated together in memory
   before publication. New-file creation is exclusive, while changed existing
   files receive numbered backups. Handled save failures roll back created files
   and restore written files when they still match the prepared changes. Source
   changes during editor use prevent saving. Source text outside the affected
   collection/member is retained, as are includes, comments and collection order.
   Literal Python collections and mappings are supported; computed collections
   must be made explicit. Addition can repair a missing definition, provided
   the resulting complete plan passes validation. Existing dependency bindings
   cannot be silently redirected by a new multipart alias.

Removing entries
----------------

``remove ID [task_file] [--kind KIND] [--owner TASK_ID] [--remove-references] [--write]``
   Preview removal of an exact ID, using the same kind/owner disambiguation as
   ``edit`` and ``rename``. An existing valid plan is required for relationship
   analysis. Incoming references block removal by default and are listed with
   their owners. ``--remove-references`` clears them without removing the owner
   tasks or other definitions::

      planner remove BUILD_WING plan.yaml
      planner remove BUILD_WING plan.yaml --remove-references
      planner remove RELEASE_GATE --kind milestone --remove-references --write
      planner remove 'aircraft/design#42' --kind workitem --owner BUILD_WING --write

   Cleanup includes incoming task dependency edges, task activity assignments,
   task milestone references, task/milestone deliverable references, and project
   dependency risk references. Outgoing fields disappear with the removed
   entry. Cleanup is not cascading task deletion. Normal validation warnings,
   including unproduced required outputs, remain visible before confirmation.

   Parent removal includes its parts and references to their expanded IDs.
   Removing the last part is rejected: remove the parent instead. When a part
   is removed, parent-alias dependencies continue to require surviving parts.
   An inherited work-item removal for one part creates a local override;
   sibling references remain unchanged. Shared owner collections are isolated
   when needed to avoid changing other owners or dependency bindings.

   In a terminal, a validated preview prompts ``Apply this removal? [y/N]:``;
   only ``y`` or ``yes`` confirms. Enter/EOF decline and Ctrl-C cancels with
   status 130. ``--write`` bypasses confirmation. Noninteractive or redirected
   input/output remains preview-only without ``--write``. Sources are rechecked
   after confirmation and before each write. Saves retain numbered backups,
   are atomic per file, and roll back handled failures as with ``rename``.

   Removing the last member of an included list retains an empty ``[]`` file
   and its include. Removing a single-mapping include detaches its directive
   without deleting the included file. No source files are deleted automatically.
   Python collections must be literal; affected YAML anchors/aliases and merged
   collection containers must first be made explicit. Both commands use the
   normal default file, data directory and ``--config`` settings. Scope is this
   plan and recursive includes, not other independent plans or configuration IDs.

Text width
----------

The general configuration's top-level ``max_width`` setting controls shared
terminal and source-formatting widths (default 80, integer minimum 40).
This includes terminal rules/prose, funding totals, help, discovery output and
newly folded YAML source. ``planner format`` uses it for Python line length.
Authored literal YAML values and export layout dimensions retain their existing
behavior. See :doc:`configuration` for scope, exceptions and help fallback.

Staff Funding
-------------

``list tasks FILE funding`` shows resolved annual totals, type amounts and staff
calculations, including available FTE, assigned percentage and annual rate.
The complete terminal document includes the same breakdown.
Configuration ``labor_costing: annual`` keeps allocations independent of task
duration; ``duration`` prorates by fiscal-year schedule overlap. ``rates_file``
selects the annual rate/staff catalog.

``split --funding equal`` accepts coarse parent budgets; typed parent funding
requires ``--funding parts`` to preserve type/staff allocations. See
:doc:`funding` for examples and calculation rules.

Summary Markdown
----------------

Word/PDF ``export`` preserves summary line breaks and blank lines while
retaining emphasis across lines, including quoted italics and bullet lists.
Use YAML ``|``/``|-`` for explicit line breaks, or ``>``/``>-`` to fold source
wrapping into paragraphs. Quotes inside literal blocks need no backslash
escaping. Word ``import`` retains the exported italic formatting.

Coded Staff Allocations
-----------------------

``list tasks FILE funding`` includes each selected staff allocation's code in
brackets. Staff catalogs and task labor entries accept optional ``code`` text;
use it when the same staff ID has multiple coded allocations. Codes match
exactly after trimming. Each person/code pair has its own available FTE and rate.
See :doc:`funding` for selection and compatibility rules.

Rates files may group code allocations under one staff entry using a ``codes``
list. Each child has ``id`` and optional ``fte``/``rate``; a shared parent rate
is inherited. Existing flat coded entries remain supported. Task labor syntax
continues to use ``id``, ``code``, and ``percent``.

Task Cost
---------

``list tasks FILE cost`` and ``list FILE cost`` display derived costs by funding
type and an overall total. Displayed costs round to whole K (halves up), after
summing exact amounts; funding output and calculations keep their precision.
Coarse funding is unclassified. The field also appears
in default task/full-document output and ``list-detail``. Configured lists opt in
with ``list.elements.tasks.cost: true`` or an ordered ``cost`` instruction. It is
output-only and cannot be authored on tasks or used as an export field.

List commands show ``Incomplete`` when rates are unavailable or required labor
duration inputs are absent, retaining any known subtotal. Affected funding and
actual/potential totals also remain incomplete. Invalid input/references still
error, and ``validate``, exports and authoring retain strict funding resolution.
See :doc:`funding` for completeness and shared-parent behavior.

Labor funding code selection
----------------------------

``list tasks FILE code`` displays the effective task funding code. Labor entries
inherit a task's ``code`` or its linked activity's ``code``; an individual labor
entry can override that default. Funding detail displays the resolved code.
See :doc:`funding` for YAML examples and clearing/inheritance rules.

Funding range shorthand
-------------------------

Typed funding accepts ``fiscal_range`` in place of a fiscal-year key to repeat
an entry across the plan's declared fiscal years. ``validate`` checks the resolved
annual entries; ``list`` funding/cost fields and exports use those same values.
Explicit-year entries override the default for that funding type and year.
See :doc:`funding` for staff and amount examples.

Shared task funding
--------------------

``validate`` resolves typed funding ``covered_by`` references after loading all
tasks, checks matching type/year/staff allocations and enforces optional
``share`` limits. ``list`` funding/cost fields display coverage separately from
direct money; funding totals count the source budget once. Share percentages
apply to source allocations, independently of receiving-task duration.

``rename`` updates coverage references. ``remove`` blocks incoming coverage
references unless ``--remove-references`` explicitly drops affected allocations.
Merge/split retain and rewrite references when the source owner is unambiguous.
See :doc:`funding` for syntax and import/export behavior.

Funding limited to task dates
-------------------------------

Typed funding ``range`` uses the task's inclusive start/end or start/expected
span. ``fiscal_range`` continues to use the plan's declared fiscal years.
Explicit year entries override either default; one type cannot specify both.
``validate`` and authoring/export commands require sufficient explicit timing
and reject ``range`` on ongoing tasks. ``list`` and ``list-detail`` can show
missing-date ranges as incomplete, retaining known explicit-year amounts in
funding/cost and annual totals. See :doc:`funding` for examples and costing rules.

Offline documentation
----------------------

``planner docs`` opens the HTML guide included with a pip installation in the
default browser. Pages, styles, search and assets are installed together and
work offline. ``planner docs --path`` prints the absolute ``index.html`` path
without opening a browser, which is useful on remote terminals. Browser launch
failure returns status 1 and reports the existing guide location.

These commands run independently of plan/configuration loading, including when
an explicit configuration path is supplied. ``planner docs --help`` and
``planner help docs`` provide the same usage help. All three shell completions
include the command and its ``--path`` option. Sphinx and Furo are build tools;
normal installed use does not require them or website hosting.

In an editable checkout, build the guide first with::

   python -m sphinx -b html docs docs/_build/html

The command recognizes that build and the standard CMake HTML output location.
A checkout without a build reports the build command; an installed package with
missing HTML reports that the package should be reinstalled.

Rates code validation
----------------------

When a rates catalog is loaded for staff funding, its flat staff ``code`` and
grouped ``codes[].id`` values must match ``XXXX_XXXX_XXXX`` (four uppercase ASCII
letters/digits per group). Invalid codes report their rates-file location.
Use underscores for dotted business codes; there is no automatic conversion.
The fictional examples use codes such as ``DEMO_CORE_0000``. Uncoded staff
entries remain supported. See :doc:`funding` for rates and allocation examples.

Child funding shares
----------------------

Multipart children may use ``share`` without ``covered_by`` to attribute the
funded parent's type/staff allocation. ``range``, ``fiscal_range`` and explicit
fiscal years use the same rules. ``validate`` permits explicit child-to-parent
coverage and checks combined child/external share limits. Cost output shows
explicit child attribution; ``--parents`` and annual financial totals retain
the authoritative parent's budget once. Ordinary inheritance is unchanged.
See :doc:`funding` for syntax, source-code selection and renaming behavior.
