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

# Copied to ~/.config/tuxfan-planner/config.yaml on first use.
# Edit your copy; package upgrades never overwrite it.
config_version: 1

# Shared text/source formatting width; integer >= 40.
max_width: 80

# Optional annual staff costs; relative to this configuration file.
# TUXFAN_PLANNER_RATES_FILE overrides this path (relative to cwd).
# rates_file: rates.yaml
# labor_costing: annual  # annual (default) or duration (scheduled months / 12)

# Optional terminal task cost breakdown (output only).
# list:
#   elements:
#     tasks:
#       id: true
#       cost: true

# Optional terminal-only color overrides. Omitted colors retain existing defaults.
# Quote hex values: YAML treats an unquoted # as a comment.
# Run planner avail colors for the complete palette and colored hex values.
# terminal:
#   colors:
#     description: "#FFFF99"
#     funding_share: "#FFFF99"  # share/remainder explanations
#     subscription:
#       available: "#00FFFF"
#       used: "#00FFFF"
#       remaining: "#00FF00"
#       ratio_low: "#FF8700"
#       ratio_critical: "#FF0000"
#       ratio: "#FFFF00"
#       proposed: "#AF875F"
#       overcommitted: "#FF0000"
#       unknown: "#FFAF00"
#     label: "#008080"
#     id: "#800080"
#     status:
#       planning: "#FF8700"
#     risk:
#       high: "#FF8700"
#     field_heading: default  # terminal's normal foreground


# Optional task ID allowlists. Omit a section to allow any non-empty value;
# an empty list permits only omitted/null/empty task values. Matching is exact.
# sites:
#   - id: Example Works
# bnrs:
#   - id: EXAMPLE-001
# Task types are built in: labor, contract, equipment, services, nonlabor.

# Optional table_entry replaces the ID only in export table cells.
# Omit it to show the canonical ID unchanged. Values must be unique within
# each vocabulary and cannot match another entry's canonical ID.
task_priorities:
  - id: safety
    label: Safety
    # table_entry: ASC 1
    description: Reduce safety risks.
  - id: capability
    label: Capability
    description: Deliver new or improved capabilities.
  - id: efficiency
    label: Efficiency
    description: Improve efficiency and use of resources.
  - id: UNSET
    label: Unset
    description: Not yet assigned; available for explicit task review assignments.

task_categories:
  - id: research
    label: Research
    # table_entry: Cat 3
    description: Investigate questions and evaluate approaches.
  - id: development
    label: Development
    description: Develop and demonstrate capabilities.
  - id: operations
    label: Operations
    description: Operate and maintain existing capabilities.
  - id: UNSET
    label: Unset
    description: Not yet assigned; imports use this for unknown categories.


# Content selection only: true or a bare entry enables a branch; mappings select children.
# Omitted children are disabled. Nested children appear in declaration order.
# Flat selections remain compatible; never define the same element in both locations.
# Task narratives and task_table are independent. Layout never enables content.
# export.structure optionally places selected sections independently of elements.
# Optional ASC profiles: asc-v4 or asc-v6. Omitted means legacy output.
# planner export --standard VERSION overrides export.standard for this invocation.
# The same literal marking appears in the header and footer; '' disables both.
export:
  # standard: asc-v6
  # header: 'CUI // EXAMPLE'
  # To use the profile's default content and table columns, omit elements/layout.
  # Per-element spacing overrides inherit layout.spacing: normal or tight.
  # For prose: summary: {spacing: tight}. A spacing-only element keeps its default content.
  elements:
    project:
    portfolios:
    managers:
    pocs:
    summary:
    background:
    fiscal_years:
    fiscal_current:
    planned_value:
    actual_value:  # calculated funded current-year task funding; colored against planned_value
    potential_value:  # calculated current-year task funding including unfunded tasks
    fiscal_range_begin:
    fiscal_range_end:
    # Optional ordered execution layout (replace the execution mapping):
    # execution:
    #   - description:
    #     heading: false  # omit or true shows the heading
    #   - activities:  # retain activity definitions; omission excludes them
    execution:
      # spacing: normal  # inherited by selected execution children unless overridden
      # Concise heading override: replace description: with these two lines:
      # description:
      #   heading: false
      description:
      # Optional ordered activity layout (replace the activities mapping):
      # activities:
      #   - spacing: tight
      #   - line: [number, label]
      #     bold: true
      #   - id:
      #   - description:
      #     heading: false  # standalone headings otherwise default to true
      activities:
        number:
        id:
        label:
        description:
        tasks: false
        task_count: false
        funding: false
      # Generated number before label uses a colon: Task A.1.1: label / Activity A: label.
      # Optional ordered task layout: replace the tasks mapping below with:
      # tasks:
      #   - spacing: tight
      #   - line:
      #       - field: number
      #         format: short  # full (the default) retains the Task prefix
      #       - id
      #       - field: label
      #         italic: true
      #       - field: status
      #         bold: false
      #         color: auto
      #     bold: true
      #   - description:
      #     heading: true  # optional; standalone field headings default to true
      #   - line: [start, end]  # end also works for start/expected task inputs
      #     heading: true  # line default; {field: end, heading: false} overrides it
      #   - line: [category, priority]
      #     color: gray
      #   - risk:
      #       type:
      #       level:
      #       mitigation:
      tasks:
        # spacing: tight
        id:
        label:
        activity:
        category:
        description:
        note: false
        site:
        bnr:
        type:
        tags:
        start:
        expected:
        completed:
        priority:
        status:
        dependencies:
        funding:
        milestones:
        deliverables:
        risk:
          type:
          level:
          description:
          mitigation:
        workitems:
          id:
          label:
          description:
          status:
          assignees:
          type:
        number:
        end:
        duration:
        state:
        funding_status: false
      # Optional ordered milestone layout: replace the milestones mapping below:
      # milestones:
      #   - line: [id, label]
      #     bold: true
      #   - description:
      #   - line: [deadline]
      #   - deliverables:
      milestones:
        # spacing: tight
        id:
        label:
        description:
        deadline:
        reporting_level:
        deliverables:
      # Optional ordered deliverable layout: replace the deliverables mapping below:
      # deliverables:
      #   - line: [id, label, status]
      #     bold: true
      #   - description:
      #   - line: [type, ready, required_by]
      #   - producers:
      deliverables:
        # spacing: tight
        id:
        label:
        description:
        type:
        status:
        completed:
        producers:
        ready:
        required_by:
    resourcing:
      # Structured project commitments; tasks.dependencies accepts task and commitment IDs.
      dependencies:
        id:
        label:
        type:
        description:
        promised:
        risks:
        tasks: false # optional derived list of tasks using this commitment
      stakeholders:
      users:
      # Includes project risks and inline task risks, independently of tasks.risk.
      # Optional ordered layout (replace risks below):
      # risks:
      #   - spacing: tight
      #   - line: [id, label]
      #     bold: true
      #   - line: [type, level]
      #   - owner:
      #   - description:
      #     heading: false
      #   - mitigation:
      risks:
        id:
        label:
        owner:
        type:
        level:
        description:
        mitigation:
        dependencies:
      task_table:
        columns:
          number:
          id: false
          label: false
          activity: false
          category: false
          description: false
          note: false
          site:
          bnr:
          type:
          tags: false
          start: false
          expected: false
          completed: false
          priority: false
          status: false
          dependencies: false
          funding:
          milestones: false
          deliverables: false
          risk: false
          workitems: false
          end: false
          duration: false
          state: false
          funding_status: false
          fiscal_funding:
        totals:
        # To add subtotals, replace the bare totals entry above with:
        # totals:
        #   activity: bottom  # or top; true/bare means bottom
        #   bnr: true  # funding total rows per B&R code
        #   unfunded: false  # true adds a separate Unfunded Total
  layout:
    context_colors: true  # automatic status/risk/priority/budget colors and table shading
    # multipart: parents  # expanded (default) or parents; standalone tasks remain visible
    # task_numbering: lettered  # Task A.a, A.b instead of the default numeric A.1, A.2
    # metadata styles never enable content; export.elements controls inclusion.
    # metadata:
    #   portfolios:
    #     heading: true
    #     heading_bold: true
    #     bold: false  # omit: bold for one value, normal for multiple values
    #   managers:
    #     heading_bold: true
    #   pocs:
    #     heading: true
    # font_size: 12  # body points; omit to retain native SVG/PowerPoint sizes
    spacing: tight  # normal matches the reference document paragraph spacing
    task_table:
      font_size: 10  # independent table size in points; half-points are supported
      columns:
        - attribute: number
          alignment: left
        - attribute: site
          label: Site
          alignment: center
        - attribute: bnr
          label: BNR
          alignment: center
        - attribute: funding
          label: Funding
          alignment: center
        - attribute: type
          label: Type
          alignment: center

# Optional terminal presentation. Omit list to retain the existing list layouts.
# list:
#   layout:
#     context_colors: true
#     task_numbering: numeric  # or lettered
#     metadata:
#       portfolios:
#         heading: true
#         heading_bold: true
#         bold: false
#   elements:
#     project:
#     summary:
#     execution:
#       description:
#       activities:
#         - line: [number, label]
#           bold: true
#         - id:
#         - description:
#     milestones:
#       - line: [id, label]
#         bold: true
#       - required_tasks:
#     tasks:
#       - line:
#           - id
#           - field: label
#             bold: true
#           - field: status
#             color: auto
#       - description:
#       - line: [category, priority]
#       - risk:
#           type:
#           level:
#           mitigation:
#     totals:  # plan-wide funding totals, printed here
#       activity:  # per-activity totals (and B&R lines with bnr)
#       bnr:  # per-B&R-code totals
#       unfunded:  # separate Unfunded Total; excluded from regular totals
#     deliverables:
# --ignore-config bypasses list presentation; cannot be combined with --config.
# Classification vocabularies and allowlists remain active for validation/labels.

# ASC layout overrides (merge into export.layout; do not add a second layout key):
# export:
#   standard: asc-v6
#   header: 'CUI // EXAMPLE'
#   layout:
#     spacing: normal  # tight preserves the compact layout
#     headings:
#       underline: false
#     task_table:
#       orientation: landscape
#       fiscal_years: [FY28, FY29, FY30, FY31, FY32, FY33]
#       columns:
#         - attribute: number
#           label: '($K)'
#         - attribute: site
#         - attribute: bnr
#         - attribute: funding_status
#         - attribute: type
#         - attribute: tags
#         - attribute: priority
#         - attribute: category
#         - attribute: fiscal_funding
# Column layout does not enable columns; select them in elements.task_table.columns.

# Minimal ASC v4 configuration (replace export, rather than adding a second key):
# export:
#   standard: asc-v4
# Profile defaults: portrait table, normal spacing, underlined headings;
# table columns: number, site, bnr, funding_status, type, tags, fiscal_funding.
# Omitting elements/layout uses profile defaults; existing selections override them.
#   layout:
#     headings:
#       underline: false
#     spacing: tight

# Separate rules by output standard (replace export with this mapping):
# export:
#   standard: asc-v6
#   header: 'CUI // EXAMPLE'
#   layout:
#     headings:
#       underline: false  # shared unless overridden below
#   standards:
#     asc-v4:
#       elements: null  # use v4 defaults instead of a shared selection
#       layout:
#         spacing: normal
#         task_table:
#           orientation: portrait
#     asc-v6:
#       elements: null  # use v6 defaults instead of a shared selection
#       layout:
#         spacing: tight
#         task_table:
#           orientation: landscape
# Precedence: built-in profile, shared export settings, selected standard block.
# Layout mappings merge; elements and ordered lists replace as a whole.
# Omitted settings inherit. Empty elements: {} disables selected content.
# All standard blocks are validated, including inactive ones.

# Optional document placement (merge into export; selections remain in elements):
# export:
#   standard: asc-v6
#   structure:
#     - project
#     - portfolios
#     - managers
#     - pocs
#     - priority
#     - summary
#     - fiscal_current
#     - planned_value
#     - actual_value
#     - potential_value
#     - execution:
#         - activities
#         - tasks
#         - milestones
#         - deliverables
#     - resourcing:
#         - dependencies
#         - stakeholders
#         - users
#         - risks
#         - task_table

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

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 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.

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:

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 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.

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 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 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, budget and subscription use nested mappings as above; dotted names such as status.planning are also accepted, but cannot duplicate a nested entry.

Staff subscription reports use the normal section headings, rules, IDs, labels and field-heading colors. Their numeric fields have separate overrides:

terminal:
  colors:
    subscription:
      available: "#00FFFF"
      used: "#00FFFF"
      remaining: "#00FF00"
      ratio_low: "#FF8700"
      ratio_critical: "#FF0000"
      ratio: "#FFFF00"
      proposed: "#AF875F"
      overcommitted: "#FF0000"
      unknown: "#FFAF00"

available colors Allocation and used colors Subscribed; both default to cyan. Available and Available If Funded use remaining (green) above 50% of allocated capacity, ratio (yellow) above 25% through 50%, ratio_low (orange) above 10% through 25%, and ratio_critical (red) at 10% or below. Unknown capacity uses unknown. Subscribed keeps its normal color. Maximum Monthly Allocation text uses the canary description color. Overcommitted use/ratios, negative balances and overcommitment period labels use overcommitted in preference to their ordinary field colors. Unknown, incomplete and N/A values use unknown. Staff, code and task identifiers use id; ownership/coverage explanations use funding_share. CSV output remains plain, and context color suppression applies to report fields while normal structural section/rule styling is retained.

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 Funding and Staff Costs for the schema and calculation rules.