A2C TUI (a2c_tui)

Textual-based terminal UI for A2C repository setup and maintenance. The TUI is a thin presentation layer over a2c_core — config loading, validation, defaults, and persistence live in core services; the TUI handles navigation, forms, and user guidance.

When to use TUI vs CLI

Surface	Best for
a2c CLI	Scripting, CI, deterministic one-shot commands, JSON output
a2c-tui / a2c tui	Interactive setup, exploring settings, validating before save

Both operate on the same .a2c/config.yaml contract validated against schemas/config.schema.json.

New repository bootstrap

If the target path is not yet an A2C repository, a2c-tui config and a2c tui config both offer to create a minimal scaffold (same as a2c init), then open the configuration wizard.

Not an A2C repository → [Yes, init scaffold] → guided config wizard

For full workflow adoption (ADR-0000, rules/, templates/, prompts/, changelog, pre-commit), run:

a2c bootstrap --path /path/to/project

See cli.md for a2c init vs a2c bootstrap scope.

Configuration editing

The first production TUI feature is repository configuration editing in two modes:

Interactive guided mode

For first-time setup or users who prefer a walkthrough.

a2c-tui config --interactive --path /path/to/repo
# or
a2c tui config --interactive --path /path/to/repo

• Welcome screen explains the flow
• Steps through important settings in a sensible order (version, workflows, id format, decomposition, optional log level)
• Explains enums and booleans in plain language
• Skips irrelevant fields (for example id-format prefixes when enforcement is off)
• Review screen before save

Editor mode (non-interactive navigation)

For experienced users who want direct access to any setting.

a2c-tui config --editor --path /path/to/repo
# or
a2c tui config --editor

• Tree navigation by section (workflows, id_format, decomposition, core)
• Main pane editor with type-appropriate controls (toggle, select, input)
• Help panel with path, current value, default, pattern, and validation messages
• Keyboard actions: Save (s), Revert (r), Validate (v), Reset field (d), Quit (q / Ctrl+Q)

Dirty and invalid fields are marked in the tree (* / !). Quitting with unsaved changes prompts for confirmation.

Screenshots

An automated tour drives the interactive flow in an empty directory and exports SVG captures of each screen. See tui-screenshots.md for the gallery.

Refresh locally:

python scripts/generate_tui_screenshots.py
# or
A2C_UPDATE_TUI_SCREENSHOTS=1 pytest tests/test_tui_config_tour.py -m integration

CI runs tests/test_tui_config_tour.py without writing to docs/ (screenshots stay in a temp dir) to verify the full bootstrap → guided → review → save path.

Validation

• Field-level validation runs as you edit (enums, regex prefixes, numeric bounds)
• Full-model validation runs before save via a2c_core Pydantic models
• Invalid existing config opens in recovery mode with defaults as a starting point and load errors surfaced

Architecture

Layer	Package	Responsibility
Domain	a2c_core.services.config_editor	Load, save, validate, path get/set
Scaffold	a2c_core.services.scaffold	init / bootstrap repository layout
Metadata	a2c_core.services.config_metadata	Schema-driven ConfigFieldMetadata catalog
Presentation	a2c_tui.presentation	Guided order, labels, enum help, visibility rules
State	a2c_tui.state	Working copy, dirty tracking, field errors
UI	a2c_tui.screens, a2c_tui.widgets	Textual screens and widgets

a2c_cli launches the TUI via subprocess (a2c tui config) without importing Textual.

Limitations (current version)

• Configuration editing only — no planning artifact dashboards yet
• No multi-layer config merge (project-local file only; see architecture/initial-contracts.md)
• Presentation overrides live in a2c_tui.presentation — extend there for new guided steps or conditional visibility

Related

• cli.md — headless commands
• architecture/package-boundaries.md — TUI vs core vs CLI
• architecture/artifact-contracts.md — .a2c/config.yaml contract
• product-development.md — local install and binary build