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"
# 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.
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:
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"
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, available
values, table entries, validation success/errors, warnings, status values,
risk levels, and budget comparisons (below, equal, above).
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.