Quick Start
===========

Project Planner accepts YAML and Python plan files. The repository includes
examples under ``planner/examples``.

Pip installations include this guide for offline use. Open it with
``planner docs``, or print its ``index.html`` location with ``planner docs --path``.
Neither command needs a plan, configuration file or internet connection.

Run these commands from the repository root:

.. code-block:: bash

   planner validate planner/examples/tasks.yaml
   planner list tasks planner/examples/tasks.yaml
   planner list deliverables planner/examples/tasks.yaml
   planner list activities planner/examples/tasks.yaml
   planner list workitems planner/examples/tasks.yaml
   planner list risks planner/examples/tasks.yaml
   planner list plan planner/examples/tasks.yaml
   planner list planner/examples/tasks.yaml label
   planner list planner/examples/tasks.yaml status assignees
   planner list-detail planner/examples/tasks.yaml
   planner summary planner/examples/tasks.yaml
   planner schedule planner/examples/tasks.yaml
   planner composite planner/examples/tasks.yaml /tmp/expanded.yaml
   # Planner initializes the default user configuration automatically on first use.
   planner export planner/examples/tasks.yaml /tmp/plan.docx
   planner export planner/examples/tasks.yaml /tmp/plan.svg
   planner export planner/examples/tasks.yaml /tmp/plan.pptx
   planner export-gantt planner/examples/tasks.yaml /tmp/gantt.svg
   planner export-gantt planner/examples/tasks.yaml /tmp/gantt.pptx

To export the same document layout as PDF on macOS or Windows with Microsoft
Word installed, use ``planner export planner/examples/tasks.yaml /tmp/plan.pdf``.
Allow automation of Word if prompted.

Import a Word Plan
------------------

To start from a document structured like a planner Word export:

.. code-block:: bash

   planner import proposal.docx
   planner validate proposal.yaml

Output defaults to ``proposal.yaml`` beside the source; an optional second
filename overrides it. The output must be a new file. Relative paths use the
current directory; planner environment overrides do not apply. Use
``--config PATH`` to identify custom table headers when needed.

Import creates a draft with label-based task IDs and review comments. Recovered
explicit IDs are preserved; generated ID collisions receive numeric suffixes. Missing forecast
start/end dates can be inferred using full-year bounds from positive annual
funding, preserving recovered timing and ``unfunded`` status where possible.
Missing status or unrecoverable required timing becomes a planning placeholder.
Review inferred dates and funding gaps before using the plan. YAML uses execution and resourcing containers; comment
dividers separate top-level fields, and blank lines separate entries with IDs.
See :doc:`cli` for recoverable fields and limitations.

Start with a Placeholder
------------------------

While developing a plan, a task needs only five task fields with ``status: planning``:

.. code-block:: yaml

   execution:
     tasks:
       - id: FUTURE_DESIGN
         category: development
         priority: capability
         label: Future design work
         description: Scope and deliverables to be developed.
         status: planning

Save this as ``draft.yaml`` and run ``planner validate draft.yaml`` or
``planner list draft.yaml``. Add estimates and risks as they become known.
Timing remains unscheduled until both ``start`` and ``expected`` are supplied;
funding estimates contribute to totals without creating dates. See :doc:`schema`.

Default Plan File
-----------------

Set ``TUXFAN_PLANNER_DATAFILE`` to omit the input file for most commands:

An empty value behaves as unset; supply an explicit input filename in that case.

.. code-block:: bash

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

Use ``list KIND FIELD`` for scoped fields (for example, ``list deliverables status``).
Run ``planner list KIND --help`` for each kind's choices. The legacy
``list [task_file] FIELD`` syntax remains available to specialize output by any supported field identifier,
such as ``label``, ``status``, ``assignees``, or ``mitigation``. Combine
field names to display several fields. Nested selections retain activity, task,
and item context; container names such as ``workitems`` show complete contents.
Combine field selection with ``--only tags=gpu`` to filter tasks first.
``label`` alone gives a compact label outline. The former ``--labels`` flag
is rejected. Run ``planner list --help`` for supported field names.
See :doc:`cli` for filtering and :doc:`composite` for splitting YAML inputs
across files. ``validate`` reports PASS/FAIL and statistics, with warning details
after the warning count.

Working with a Data Directory
-----------------------------

To select among multiple plan files without typing their directory each time:

.. code-block:: bash

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

Relative input names use that directory in preference to the current directory.
If the file is missing there, the same relative filename is tried in the current directory.
Absolute input paths bypass it. Output paths, export-options paths, and relative
include paths keep their existing meanings. Set ``TUXFAN_PLANNER_DATAFILE`` as
well to choose a default filename. See :doc:`development-data` for the canonical
fictional fixture used for development.

Shell Completion
----------------

The CLI prints completion scripts for ``bash``, ``zsh``, and ``fish``:

.. code-block:: bash

   planner completion bash
   planner completion zsh
   planner completion fish

For a one-session bash setup:

.. code-block:: bash

   source <(planner completion bash)

Full Terminal Plans
-------------------

``planner list tasks.yaml`` displays the entire planning document in the
terminal. Export selection, columns, and note settings do not limit it.
``planner list tasks tasks.yaml`` keeps the compact task-only view, while
``planner list tasks.yaml summary tasks`` uses existing field projections.
Normal color, wrapping, filtering, and paging controls apply.

Find Command Help
-----------------

Use ``planner help`` for the command overview, ``planner help fields`` for
mapping templates, or ``planner list help tasks`` for scoped task-list help.
These are aliases for the corresponding ``--help`` forms and use the same
colors and pager without loading a plan or initializing configuration.
