# TypeDialog Configuration Structure\n\nThis directory contains TypeDialog forms, templates, and configuration data organized by subsystem.\n\n## Directory Organization\n\n```\n.typedialog/\n├── core/           # Core subsystem forms (setup, auth, infrastructure)\n├── provisioning/   # Main provisioning configuration fragments\n└── platform/       # Platform services forms (future)\n```\n\n### Why Multiple Subdirectories\n\nDifferent subsystems have different form requirements:\n\n1. **`core/`** - Core infrastructure operations\n   - System setup wizard\n   - Authentication (login, MFA)\n   - Infrastructure confirmations (delete, deploy)\n   - **Users**: Developers, operators\n\n2. **`provisioning/`** - Project provisioning configuration\n   - Deployment target selection (docker, k8s, ssh)\n   - Database configuration (postgres, mysql, sqlite)\n   - Monitoring setup\n   - **Users**: Project setup, CI/CD\n\n3. **`platform/`** (future) - Platform services\n   - Orchestrator configuration\n   - Control center setup\n   - Service-specific forms\n   - **Users**: Platform administrators\n\n## Structure Within Each Subdirectory\n\nEach subdirectory follows this pattern:\n\n```\n{subsystem}/\n├── forms/          # TOML form definitions\n├── templates/      # Nickel/Jinja2 templates\n├── defaults/       # Default configurations\n├── constraints/    # Validation rules\n└── generated/      # Generated configs (gitignored)\n```\n\n## Core Subsystem (`core/`)\n\n**Purpose**: Core infrastructure operations (setup, auth, confirmations)\n\n**Forms**:\n- `forms/setup-wizard.toml` - Initial system setup\n- `forms/auth-login.toml` - User authentication\n- `forms/mfa-enroll.toml` - MFA enrollment\n- `forms/infrastructure/*.toml` - Delete confirmations (server, cluster, taskserv)\n\n**Bash Wrappers** (TTY-safe):\n- `../../core/shlib/setup-wizard-tty.sh`\n- `../../core/shlib/auth-login-tty.sh`\n- `../../core/shlib/mfa-enroll-tty.sh`\n\n**Usage**:\n```\n# Run setup wizard\n./provisioning/core/shlib/setup-wizard-tty.sh\n\n# Nushell reads result\nlet config = (open provisioning/.typedialog/core/generated/setup-wizard-result.json | from json)\n```\n\n## Provisioning Subsystem (`provisioning/`)\n\n**Purpose**: Main provisioning configuration (deployments, databases, monitoring)\n\n**Structure**:\n- `form.toml` - Main provisioning form\n- `fragments/` - Modular form fragments\n  - `deployment-*.toml` - Docker, K8s, SSH deployments\n  - `database-*.toml` - Database configurations\n  - `monitoring.toml` - Monitoring setup\n  - `auth-*.toml` - Authentication methods\n- `constraints.toml` - Validation constraints\n- `defaults/` - Default values\n- `schemas/` - Nickel schemas\n\n**Usage**:\n```\n# Configure provisioning\nnu provisioning/.typedialog/provisioning/configure.nu --backend web\n```\n\n## Platform Subsystem (`platform/` - Future)\n\n**Purpose**: Platform services configuration\n\n**Planned forms**:\n- Orchestrator configuration\n- Control center setup\n- MCP server configuration\n- Vault service setup\n\n**Status**: Structure planned, not yet implemented\n\n## Integration with Code\n\n### Bash Wrappers (TTY-safe)\n\nLocated in: `provisioning/core/shlib/*-tty.sh`\n\nThese wrappers solve Nushell's TTY input limitations by:\n1. Handling interactive input in bash\n2. Calling TypeDialog with proper TTY forwarding\n3. Generating JSON output for Nushell consumption\n\n**Pattern**:\n```\nBash wrapper → TypeDialog (TTY input) → Nickel config → JSON → Nushell\n```\n\n### Nushell Integration\n\nLocated in: `provisioning/core/nulib/lib_provisioning/`\n\nFunctions that call the bash wrappers:\n- `setup/wizard.nu::run-setup-wizard-interactive`\n- `plugins/auth.nu::login-interactive`\n- `plugins/auth.nu::mfa-enroll-interactive`\n\n## Generated Files\n\n**Location**: `{subsystem}/generated/`\n\n**Files**:\n- `*.ncl` - Nickel configuration files\n- `*.json` - JSON exports for Nushell\n- `*-defaults.ncl` - Default configurations\n\n**Note**: All generated files are gitignored\n\n## Form Naming Conventions\n\n1. **Top-level forms**: `{purpose}.toml`\n   - Example: `setup-wizard.toml`, `auth-login.toml`\n\n2. **Fragment forms**: `fragments/{category}-{variant}.toml`\n   - Example: `deployment-docker.toml`, `database-postgres.toml`\n\n3. **Infrastructure forms**: `forms/infrastructure/{operation}_{resource}_confirm.toml`\n   - Example: `server_delete_confirm.toml`\n\n## Adding New Forms\n\n### For Core Operations\n\n1. Create form: `.typedialog/core/forms/{operation}.toml`\n2. Create wrapper: `core/shlib/{operation}-tty.sh`\n3. Integrate in Nushell: `core/nulib/lib_provisioning/`\n\n### For Provisioning Config\n\n1. Create fragment: `.typedialog/provisioning/fragments/{category}-{variant}.toml`\n2. Update main form: `.typedialog/provisioning/form.toml`\n3. Add defaults: `.typedialog/provisioning/defaults/`\n\n### For Platform Services (Future)\n\n1. Create subsystem: `.typedialog/platform/`\n2. Follow same structure as `core/` or `provisioning/`\n3. Document in this README\n\n## Related Documentation\n\n- **Bash wrappers**: `provisioning/core/shlib/README.md`\n- **TypeDialog integration**: `provisioning/platform/.typedialog/README.md`\n- **Nushell setup**: `provisioning/core/nulib/lib_provisioning/setup/wizard.nu`\n\n---\n\n**Last Updated**: 2025-01-09\n**Structure Version**: 2.0 (Multi-subsystem organization)