General Configuration
=====================

Planner requires a general YAML configuration for operational commands. The
package includes a default file, copied on first use to
``~/.config/tuxfan-planner/config.yaml``. When ``XDG_CONFIG_HOME`` is set, it
must be absolute and replaces ``~/.config``. Initialization is reported on
stderr. Help and completion generation do not initialize the file.

Create the file explicitly with::

   planner config init

To print a complete editable template to stdout instead, use::

   planner fields config > team-config.yaml

This template uses packaged defaults and includes an explicit ``export.elements``
tree containing every supported element and child field, plus commented
optional allowlists and table layout examples. The renderer determines
output order; ordering the selection list does not reorder a document. It works without a valid existing configuration, does
not initialize one, and ignores ``--config``. Other ``fields`` templates continue
to use the active configuration for vocabulary examples.

Edit this user copy to customize vocabularies and export settings. Upgrades
never overwrite it. Initialization refuses existing files. ``--config PATH``
selects an alternate file, relative to the current directory or absolute, and
can appear before or after the command::

   planner config init --config team-config.yaml
   planner validate plan.yaml --config team-config.yaml
   planner --config team-config.yaml list plan plan.yaml

Explicit missing files and existing invalid/unreadable files are errors. There
is no fallback or implicit merging with packaged settings. Each configuration
must contain version 1, both labeled vocabularies, and an ``export`` mapping.
The task ID allowlists described below are optional.

Packaged Default
----------------

.. literalinclude:: ../planner/default-config.yaml
   :language: yaml

``task_priorities`` and ``task_categories`` entries require unique, non-empty ``id`` values and non-empty
``label`` and ``description`` strings. IDs contain ASCII letters, digits, and underscores.
Values are trimmed, then matched case-sensitively. Unknown keys, duplicate YAML
keys, unsupported versions, and empty vocabularies are rejected with source
locations. Configuration files do not support includes or executable Python.

Classification Table Labels
---------------------------

Both ``task_categories`` and ``task_priorities`` accept an optional
``table_entry`` on each entry::

   task_categories:
     - id: INVEST
       label: Research and investment
       table_entry: Cat 3
       description: Explore future capabilities.

   task_priorities:
     - id: CAPABILITY
       label: Mission capability
       table_entry: ASC 1
       description: Support mission needs.

Task narratives and terminal task displays use ``label``. Export table cells
use ``table_entry`` when supplied, otherwise the canonical ``id`` unchanged.
There are no automatic CAT/ASC conversions. ``table_entry`` must be non-empty
text when supplied; surrounding whitespace is trimmed and spelling/case are
preserved. Effective table values must be unique within each vocabulary, and
an explicit table label cannot match another entry's canonical ID. Different
vocabularies may use the same table label. Labels remain free to repeat.

``avail category`` and ``avail priority`` show explicit table labels alongside
IDs, labels, and descriptions. Plans, filters, ``show``, and task/plan templates
continue to use canonical IDs. Word import recognizes canonical IDs and explicit
table labels, using table values to disambiguate repeated narrative labels.
Existing numbered IDs require explicit table labels to retain the former
spaced table spelling, for example ``id: ASC_1`` with ``table_entry: ASC 1``.

Task ID Allowlists
------------------

Optional ``sites`` and ``bnrs`` sections restrict the corresponding
task fields ``site`` and ``bnr``. Each entry is a mapping with
only a required non-empty string ``id``; labels are not required or accepted::

   sites:
     - id: Workshop One
     - id: Workshop Two
   bnrs:
     - id: EXAMPLE-001
     - id: EXAMPLE-002

Each task chooses at most one ``site`` and one ``bnr`` ID, for example
``site: Workshop One``. ``type`` accepts one ID or a list of IDs, for work that
combines types::

   type: [labor, equipment]

Task types are built in: ``labor``, ``contract``, ``equipment``, ``services``,
``nonlabor``.
The configuration ``types`` section is no longer accepted; remove it from
existing configurations. Every listed type must use one of these IDs;
duplicates are dropped, keeping the first occurrence, and empty or structured list entries are errors. A single text
value is never split, so ``type: labor, equipment`` is rejected. Different
tasks may choose different IDs. Other lists and mappings in task fields are
invalid. Configured IDs and task values are trimmed and matched exactly,
including case. Configured site/bnr IDs may contain spaces and hyphens; quote
numeric IDs. Duplicate
IDs and unknown entry keys are errors. The strings ``none`` and ``null``
(ignoring case) are reserved for clearing optional task values.

Omitting a site/bnr section leaves that field unrestricted, preserving existing
configurations. A supplied empty list allows only omitted/null/empty task
values; a null configuration section is invalid. These fields remain optional.
Validation applies to effective values after task defaults and multipart
inheritance, including YAML includes and Python sources. An explicit null or
empty task value clears an inherited value. Task ``type`` restrictions do not
change deliverable types, risk types, or derived work item types.

All plan exports continue to display these IDs as optional task attributes;
select the corresponding export columns/attributes as usual. ``avail site``
and ``avail bnr`` print configured IDs without loading a plan,
return no values for an empty allowlist, and report an error when the section is
omitted. ``avail type`` always lists the five built-in task types.
``fields task`` and ``fields plan`` choose the first configured ID
(or an empty value for an empty allowlist) for their examples.

Plan References
---------------

.. code-block:: yaml

   project: Aircraft Development
   tasks:
     - id: WING_DESIGN
       category: development
       priority: capability
       label: Design the wing
       description: Produce the initial design.
       status: planning

Tasks optionally specify one scalar ``priority`` ID from ``task_priorities``.
Omitted/null/empty text means unassigned. Defaults and multipart inheritance
apply; explicit IDs replace inherited values and null/empty text clears them.
Lists, mappings, non-string values, and unknown IDs are rejected.
Every effective task requires one scalar ``category`` ID from ``task_categories``;
that field cannot be cleared.

``avail priority`` and ``avail category`` print active IDs, labels, and descriptions.
``fields plan`` and ``fields task`` use the active vocabulary. Use
``list tasks FILE priority``, ``show tasks.priority``, and
``--only priority=capability`` to inspect and filter assignments.
Task narratives and all terminal task displays use configured category and
priority labels. List views append a light-cyan bracketed canonical ID;
export narratives retain labels. Tables use optional ``table_entry`` values,
falling back to IDs.
Table column ``priority`` reads each task. There is no project priority element
or calculated primary priority.

Migration
---------

Add a non-empty ``label`` to every existing vocabulary entry. Labels are display
names; plan references continue to use IDs. Labels need not be unique.

Use ``export.elements`` for all content selection and ``export.layout`` for
presentation. ``export.standard: asc-v6`` selects the ASC v6 defaults;
``export.header`` supplies identical header/footer text. The heading underline,
table orientation and fiscal display years can be overridden under layout.
``export.layout.spacing: normal`` uses the reference document's paragraph
spacing; ``tight`` (the default) retains the compact spacing. This also adapts
plan SVG and PowerPoint paragraph spacing without changing list or Gantt layouts.
See :doc:`export-options` for a complete example. Existing configurations without
a standard retain legacy defaults. Replace legacy element-name lists with boolean mappings,
move note selection to ``elements.tasks.note``, and move table selection/styles
to ``elements.task_table.columns`` and ``layout.task_table.columns``.
``export: {}`` selects all content, including notes; the packaged explicit
selection disables notes.
Replace ``--export-options`` with ``--config``. The environment variable
``TUXFAN_PLANNER_EXPORT_OPTIONS`` is no longer read or displayed.

Use the explicit YAML migration to move former project assignments into task-list
defaults and rename the vocabulary/table selections. It reports changes by
default; ``--write`` creates numbered backups and applies them:

.. code-block:: bash

   planner migrate-priorities FY27 --config configs/asc.yaml
   planner migrate-priorities FY27 --config configs/asc.yaml --write

Singleton legacy lists become scalar priority IDs; multiple IDs and legacy
urgency values require an explicit choice. Includes remain includes.
Conflicting project/default assignments and duplicate
old/new vocabulary definitions stop before writing. All files are prepared
before any are saved; multi-file saves are not one atomic transaction.
Unrelated older schema errors still need review. Migrate Python plan files
manually by placing priorities on task records and removing the project field.
Word import recovers priorities per task; older document-wide assignments are
copied only to tasks without an explicit assignment, with a review notice.
Missing task priorities remain empty. Missing categories still use a review
placeholder.

The configuration template uses bare entries for enabled export content and
explicit false values for disabled fields. Formatting booleans such as bold
remain explicit.

Export Selection
----------------

``export.elements`` is a nested mapping of booleans and child mappings for all
four plan export formats. Omitted/null elements includes all content; ``{}``
selects none. Bare entries (YAML null) enable a branch or field, just like true.
Inside a mapping, omitted children are disabled. Task narrative fields
and table columns are selected independently. Layout only styles enabled table
columns. Risk is part of task narratives; there is no separate mitigation
section. See :doc:`export-options` for syntax, table controls, and migration.

Task export content can also be an ordered list with repeated line instructions
and interleaved standalone fields. The fields config template includes a
commented replacement layout; previous task line/lines mappings remain accepted.

Milestones and deliverables also accept ordered instruction lists with repeated
line entries and per-field styles. Their relationship lists remain standalone
fields. The fields config template includes examples for both sections.

Terminal List Presentation
--------------------------

The optional ``list`` section selects terminal content independently of export.
Omitting it retains existing layouts. It accepts ``elements`` with the
shared selection and ordered instruction syntax, plus ``layout`` with
``context_colors``, ``task_numbering`` and ``metadata`` styles. ``task_numbering``
is ``numeric`` (default) or ``lettered``. ``context_colors`` defaults to true;
false neutralizes automatic status/risk/budget colors while preserving
explicit field colors. Metadata styles for ``portfolios``, ``managers`` and
``pocs`` accept ``heading``, ``heading_bold`` and ``bold`` booleans; omitted
value bold uses the shared single/multiple-value rule. Bare entries include content;
omitted mapping children exclude it. Null/omitted elements includes the complete
document. Scalar elements, nested selections and tasks/milestones/deliverables
support the same shapes as export. Compatibility kinds activities, workitems,
risks, and plan can also be selected, with their scoped terminal fields.

.. code-block:: yaml

   list:
     elements:
       project:
       milestones:
         - line: [id, label]
           bold: true
         - required_tasks:
       tasks:
         - line: [id, label, status]
           bold: true
         - description:
         - risk:
             mitigation:
       deliverables:

Terminal relationships and derived fields come from the shared listing registry;
examples include milestone direct_tasks/producer_tasks/required_tasks, activity
task_count/funding, and deliverable producers/ready/required_by/assessment.
Task computed number/end/duration/state/funding_status and nested work-item type
are also available. Structured fields require standalone instructions; scalar
fields can appear in lines. Layout/task_table controls remain export-only.

Explicit kinds override top-level omissions; existing formatting for an enabled
kind remains applicable. Explicit positional fields use the existing projection
layout and override configured content/layout. Filters continue to operate on
complete records before rendering, preserving full-plan dates and numbering.
Styled lines wrap at the configured width (80 visible columns by default). Named/hex colors adapt to ANSI, semantic
status colors and ID highlighting remain available, and existing color/NO_COLOR
and pager behavior stays authoritative.

``planner list --ignore-config`` bypasses list content/layout and prints complete
records (with explicit kinds/fields/filters still honored). It also bypasses
invalid list presentation, but still loads and validates classification settings
and the remaining configuration. Combining it with explicit ``--config`` is an
argument error before loading any file. The option works before or after the
list kind; it is rejected for other commands.

``planner fields config`` includes a commented list example; it does not enable
terminal configuration by default or modify an existing user file.

List Formatting Inheritance
---------------------------

Enabling list configuration does not restyle unrelated content. Bare elements
reuse the standard renderer for their requested scope: full-document tasks keep
activity grouping and details, while explicitly scoped tasks keep the compact
layout unless complete output was requested. Field mappings use the standard
scoped field renderer after applying selection. Standalone instructions retain
normal field colors, indentation, wrapping and relationship bullets.

Custom lines inherit semantic defaults: task labels/numbers are cyan, identity
IDs are bold magenta, definition labels retain heading emphasis, and status
values use their normal status colors. Closed/unfunded tasks retain subdued
colors. Explicit line/field colors override those defaults; explicit false
emphasis overrides inherited emphasis. Fixed category emphasis remains unchanged.

Task field headings use bold emphasis consistently across terminal list layouts,
including standalone instructions and nested risk/work-item details. Values
retain normal text/semantic colors and explicit line styles remain authoritative.
Risk entries are unnumbered and repeat their header for each entry.

Terminal Risk headers are bold and severity-colored (low green, medium yellow,
high orange, extreme red). Severity remains available for header styling when
the level text is omitted from configured selections. This display metadata is
not a plan input field. Existing muted value colors and color controls remain
in effect; disabling color produces the same plain text.

Execution also accepts ordered instructions under ``export.elements`` and
``list.elements``. For example, ``execution:`` may contain ``- description:``
with sibling ``heading: false``, followed by ``- activities:``. This suppresses
only the description heading, keeps the prose and selected activities, and
preserves instruction order. Omitted/true heading retains the heading. See
:doc:`export-options` for a complete example.

The equivalent concise form is ``execution: {description: {heading: false},
activities: null}``. Description style mappings accept only the boolean heading
setting; omitted heading retains the default. Both forms work for export and
list presentation.

Per-element export spacing
--------------------------

``export.layout.spacing`` remains the document default. Export narrative elements
can override it with ``spacing: normal`` or ``spacing: tight`` in a selection
mapping or a standalone ``- spacing: tight`` instruction. Tasks, milestones,
deliverables, execution/activities, prose sections and multi-value metadata share
this policy. A spacing-only entry retains bare-element content; omitted spacing
inherits. ``fields config`` includes examples. Tables retain their independent
cell layout; terminal list spacing is unchanged. See :doc:`export-options` for
all supported scopes and inheritance rules.

Terminal colors
---------------

Customize terminal output with an optional ``terminal.colors`` mapping::

   terminal:
     colors:
       description: "#FFFF99"
       funding_share: "#FFFF99"
       label: "#008080"
       id: "#800080"
       field_heading: default
       status:
         planning: "#FF8700"
       risk:
         high: "#FF8700"

Only supplied attributes change; omitted attributes retain existing ANSI defaults.
Values must be quoted six-digit hexadecimal colors or ``default`` (the terminal's
normal foreground). Invalid colors and unknown attributes are errors.
``status``, ``risk`` and ``budget`` use nested mappings as above; dotted names
such as ``status.planning`` are also accepted, but cannot duplicate a nested entry.

List every attribute, its conventional default hex equivalent, effective value
with both values rendered in their colors and attribute names in bold cyan
(default ``#008080``, overridden by ``label``). Item rules separate entries
and use the ``item_rule`` palette color::

   planner avail colors
   planner avail colors --config team-config.yaml
   planner avail colors --color always

Attributes cover description prose, labels, IDs, bracketed classification IDs,
field/section headings, section/subsection/item rules, funding amounts, share
and remainder explanations (``funding_share``), available values, table entries, validation success/errors, warnings, status values,
risk levels, and budget comparisons (``below``, ``equal``, ``above``).
``funding_share`` colors terminal cost share/source and remainder explanations.
It defaults to canary ``#FFFF99``, the same default as ``description``, and can
be overridden independently. Staff/source IDs and codes retain the ``id`` color;
closed/unfunded task colors take precedence over share coloring.
``planner fields config`` includes a commented example.

Standard ANSI colors depend on the terminal theme, so their displayed default
hex equivalents are conventional approximations. Indexed and RGB defaults have
fixed RGB equivalents. Omitting an override preserves the existing ANSI code;
supplying a hex value requests that exact RGB color on a truecolor terminal.
Legacy list-detail high-risk text retains its red default; an explicit
``risk.high`` override applies consistently to all terminal views.

Explicit configured field colors take precedence over palette defaults;
``color: auto`` uses the palette, while field ``color: default`` retains its
existing uncolored behavior. Closed/unfunded task styling still applies to
headings and attributes; descriptions use their own palette color.
``layout.context_colors: false`` continues to suppress contextual semantic colors.
Structural colors retain their existing behavior. ``--color never`` suppresses
all styling; automatic color honors ``NO_COLOR``, ``TERM=dumb`` and redirection.
Paging preserves colored hex values. Terminal overrides do not change document,
slide or Gantt export palettes.

To print the complete effective palette as plain, config-ready YAML::

   planner fields colors
   planner fields colors --config team-config.yaml > colors.yaml

Paste the emitted ``terminal.colors`` mapping into your general configuration,
replacing any existing ``terminal`` section. Output includes every attribute,
with nested ``status``, ``risk`` and ``budget`` mappings. Existing overrides and
``default`` values are retained; omitted attributes use conventional default hex
values. Explicit hex definitions replace theme-dependent ANSI defaults with
fixed RGB colors. This is a configuration fragment, not a complete configuration;
``fields config`` remains the complete packaged-default template.

Editing the active configuration
--------------------------------

Open the active configuration in your editor with::

   planner config edit
   planner config edit --config team-config.yaml

``config edit`` is an alias for ``edit config`` and uses the identical workflow.

The editor comes from ``TUXFAN_PLANNER_EDITOR`` or, if unset/empty, ``EDITOR``.
GUI editors must wait until editing finishes (for example, ``code --wait``).
Planner validates the entire edited configuration before an atomic save and
keeps a numbered backup. Invalid edits can be reopened or cancelled, and failed
buffers are retained at the printed path. Existing invalid configurations can
be repaired. An unchanged buffer does not create a backup. No plan is loaded.
Missing implicit defaults are initialized normally; explicitly selected missing
files are errors. Symbolic links are preserved, with backups beside the resolved
target; concurrent source or link-target changes prevent saving.

Maximum text width
------------------

Set a shared maximum text width in the general configuration::

   config_version: 1
   max_width: 100

``max_width`` defaults to 80 and must be an integer of at least 40. It is a
top-level setting, independent of ``terminal.colors`` and list/export selection.
Omitted settings retain the 80-column default; existing configs need no migration.

The width controls terminal prose, headings and rules, relationship lists,
funding totals (including year-block splitting), ``avail`` output, command help,
and wrapped CLI errors. Nested views subtract their indentation. Terminal
wrapping measures visible columns without counting ANSI color codes.
Spellcheck suggestions use the smaller of this limit and the terminal width.

Source formatting uses the same limit for newly generated/folded YAML prose,
import section dividers, merge/split output and editor-generated source.
``planner format`` passes it to Black as the Python line length. Authored YAML
block styles and values remain protected: literal blocks and existing explicit
fold positions are not forcibly reflowed. Unbreakable YAML values or Python
strings can exceed the limit when splitting them would change content.
Copyable identifiers in discovery output retain their existing wrapping policy.

Help reads the selected config's width without initializing a missing file;
missing or malformed settings fall back to 80 so help and config repair remain
usable. Normal commands reject invalid widths. ``fields config``, completion
scripts and version output retain their config-independent bootstrap behavior.
The complete config template includes ``max_width: 80``.

Document page sizes, fonts, table widths, slide geometry, Gantt geometry and
export colors are unchanged. Programmatic renderer arguments specifying a local
width continue to override the default. Render contexts are isolated between
invocations.

Staff Rates and Labor Costing
-----------------------------

Optional ``rates_file: rates.yaml`` selects annual full-time staff rates, relative
to this configuration file. ``TUXFAN_PLANNER_RATES_FILE`` overrides the path.
Optional ``labor_costing`` is ``annual`` (the default) or ``duration``. Staff
``fte`` scales availability and task ``percent`` selects a share of that effort.
See :doc:`funding` for the schema and calculation rules.
