# CI System - Configuration Guide\n\n**Installed**: 2026-01-01\n**Detected Languages**: rust, nushell, nickel, bash, markdown, python, javascript\n\n---\n\n## Quick Start\n\n### Option 1: Using configure.sh (Recommended)\n\nA convenience script is installed in `.typedialog/ci/`:\n\n```\n# Use web backend (default) - Opens in browser\n.typedialog/ci/configure.sh\n\n# Use TUI backend - Terminal interface\n.typedialog/ci/configure.sh tui\n\n# Use CLI backend - Command-line prompts\n.typedialog/ci/configure.sh cli\n```\n\n**This script automatically:**\n\n- Sources `.typedialog/ci/envrc` for environment setup\n- Loads defaults from `config.ncl` (Nickel format)\n- Uses cascading search for fragments (local → Tools)\n- Creates backup before overwriting existing config\n- Saves output in Nickel format using nickel-roundtrip with documented template\n- Generates `config.ncl` compatible with `nickel doc` command\n\n### Option 2: Direct TypeDialog Commands\n\nUse TypeDialog nickel-roundtrip directly with manual paths:\n\n#### Web Backend (Recommended - Easy Viewing)\n\n```\ncd .typedialog/ci  # Change to CI directory\nsource envrc  # Load environment\ntypedialog-web nickel-roundtrip config.ncl form.toml \\n  --output config.ncl \\n  --ncl-template $TOOLS_PATH/dev-system/ci/templates/config.ncl.j2\n```\n\n#### TUI Backend\n\n```\ncd .typedialog/ci\nsource envrc\ntypedialog-tui nickel-roundtrip config.ncl form.toml \\n  --output config.ncl \\n  --ncl-template $TOOLS_PATH/dev-system/ci/templates/config.ncl.j2\n```\n\n#### CLI Backend\n\n```\ncd .typedialog/ci\nsource envrc\ntypedialog nickel-roundtrip config.ncl form.toml \\n  --output config.ncl \\n  --ncl-template $TOOLS_PATH/dev-system/ci/templates/config.ncl.j2\n```\n\n**Note:** The `--ncl-template` flag uses a Tera template that adds:\n\n- Descriptive comments for each section\n- Documentation compatible with `nickel doc config.ncl`\n- Consistent formatting and structure\n\n**All backends will:**\n\n- Show only options relevant to your detected languages\n- Guide you through all configuration choices\n- Validate your inputs\n- Generate config.ncl in Nickel format\n\n### Option 3: Manual Configuration\n\nEdit `config.ncl` directly:\n\n```\nvim .typedialog/ci/config.ncl\n```\n\n---\n\n## Configuration Format: Nickel\n\n**This project uses Nickel format by default** for all configuration files.\n\n### Why Nickel?\n\n- ✅ **Typed configuration** - Static type checking with `nickel typecheck`\n- ✅ **Documentation** - Generate docs with `nickel doc config.ncl`\n- ✅ **Validation** - Built-in schema validation\n- ✅ **Comments** - Rich inline documentation support\n- ✅ **Modular** - Import/export system for reusable configs\n\n### Nickel Template\n\nThe output structure is controlled by a **Tera template** at:\n\n- **Tools default**: `$TOOLS_PATH/dev-system/ci/templates/config.ncl.j2`\n- **Local override**: `.typedialog/ci/config.ncl.j2` (optional)\n\n**To customize the template:**\n\n```\n# Copy the default template\ncp $TOOLS_PATH/dev-system/ci/templates/config.ncl.j2 \\n   .typedialog/ci/config.ncl.j2\n\n# Edit to add custom comments, documentation, or structure\nvim .typedialog/ci/config.ncl.j2\n\n# Your template will now be used automatically\n```\n\n**Template features:**\n\n- Customizable comments per section\n- Control field ordering\n- Add project-specific documentation\n- Configure output for `nickel doc` command\n\n### TypeDialog Environment Variables\n\nYou can customize TypeDialog behavior with environment variables:\n\n```\n# Web server configuration\nexport TYPEDIALOG_PORT=9000           # Port for web backend (default: 9000)\nexport TYPEDIALOG_HOST=localhost      # Host binding (default: localhost)\n\n# Localization\nexport TYPEDIALOG_LANG=en_US.UTF-8    # Form language (default: system locale)\n\n# Run with custom settings\nTYPEDIALOG_PORT=8080 .typedialog/ci/configure.sh web\n```\n\n**Common use cases:**\n\n```\n# Access from other machines in network\nTYPEDIALOG_HOST=0.0.0.0 TYPEDIALOG_PORT=8080 .typedialog/ci/configure.sh web\n\n# Use different port if 9000 is busy\nTYPEDIALOG_PORT=3000 .typedialog/ci/configure.sh web\n\n# Spanish interface\nTYPEDIALOG_LANG=es_ES.UTF-8 .typedialog/ci/configure.sh web\n```\n\n## Configuration Structure\n\nYour config.ncl is organized in the `ci` namespace (Nickel format):\n\n```\n{\n  ci = {\n    project = {\n      name = "rust",\n      detected_languages = ["rust, nushell, nickel, bash, markdown, python, javascript"],\n      primary_language = "rust",\n    },\n    tools = {\n      # Tools are added based on detected languages\n    },\n    features = {\n      # CI features (pre-commit, GitHub Actions, etc.)\n    },\n    ci_providers = {\n      # CI provider configurations\n    },\n  },\n}\n```\n\n## Available Fragments\n\nTool configurations are modular. Check `.typedialog/ci/fragments/` for:\n\n- rust-tools.toml - Tools for rust\n- nushell-tools.toml - Tools for nushell\n- nickel-tools.toml - Tools for nickel\n- bash-tools.toml - Tools for bash\n- markdown-tools.toml - Tools for markdown\n- python-tools.toml - Tools for python\n- javascript-tools.toml - Tools for javascript\n- general-tools.toml - Cross-language tools\n- ci-providers.toml - GitHub Actions, Woodpecker, etc.\n\n## Cascading Override System\n\nThis project uses a **local → Tools cascading search** for all resources:\n\n### How It Works\n\nResources are searched in priority order:\n\n1. **Local files** (`.typedialog/ci/`) - **FIRST** (highest priority)\n2. **Tools files** (`$TOOLS_PATH/dev-system/ci/`) - **FALLBACK** (default)\n\n### Affected Resources\n\n| Resource | Local Path | Tools Path |\n| ---------- | ------------ | ------------ |\n| Fragments | `.typedialog/ci/fragments/` | `$TOOLS_PATH/dev-system/ci/forms/fragments/` |\n| Schemas | `.typedialog/ci/schemas/` | `$TOOLS_PATH/dev-system/ci/schemas/` |\n| Validators | `.typedialog/ci/validators/` | `$TOOLS_PATH/dev-system/ci/validators/` |\n| Defaults | `.typedialog/ci/defaults/` | `$TOOLS_PATH/dev-system/ci/defaults/` |\n| Nickel Template | `.typedialog/ci/config.ncl.j2` | `$TOOLS_PATH/dev-system/ci/templates/config.ncl.j2` |\n\n### Environment Setup (.envrc)\n\nThe `.typedialog/ci/.envrc` file configures search paths:\n\n```\n# Source this file to load environment\nsource .typedialog/ci/.envrc\n\n# Or use direnv for automatic loading\necho 'source .typedialog/ci/.envrc' >> .envrc\n```\n\n**What's in .envrc:**\n\n```\nexport NICKEL_IMPORT_PATH="schemas:$TOOLS_PATH/dev-system/ci/schemas:validators:..."\nexport TYPEDIALOG_FRAGMENT_PATH=".:$TOOLS_PATH/dev-system/ci/forms"\nexport NCL_TEMPLATE="<local or Tools path to config.ncl.j2>"\nexport TYPEDIALOG_PORT=9000           # Web server port\nexport TYPEDIALOG_HOST=localhost      # Web server host\nexport TYPEDIALOG_LANG="${LANG}"       # Form localization\n```\n\n### Creating Overrides\n\n**By default:** All resources come from Tools (no duplication).\n\n**To customize:** Create file in local directory with same name:\n\n```\n# Override a fragment\ncp $TOOLS_PATH/dev-system/ci/fragments/rust-tools.toml \\n   .typedialog/ci/fragments/rust-tools.toml\n\n# Edit your local version\nvim .typedialog/ci/fragments/rust-tools.toml\n\n# Override Nickel template (customize comments, structure, nickel doc output)\ncp $TOOLS_PATH/dev-system/ci/templates/config.ncl.j2 \\n   .typedialog/ci/config.ncl.j2\n\n# Edit to customize documentation and structure\nvim .typedialog/ci/config.ncl.j2\n\n# Now your version will be used instead of Tools version\n```\n\n**Benefits:**\n\n- ✅ Override only what you need\n- ✅ Everything else stays synchronized with Tools\n- ✅ No duplication by default\n- ✅ Automatic updates when Tools is updated\n\n**See:** `$TOOLS_PATH/dev-system/ci/docs/cascade-override.md` for complete documentation.\n\n## Testing Your Configuration\n\n### Validate Configuration\n\n```\nnu $env.TOOLS_PATH/dev-system/ci/scripts/validator.nu \\n  --config .typedialog/ci/config.ncl \\n  --project . \\n  --namespace ci\n```\n\n### Regenerate CI Files\n\n```\nnu $env.TOOLS_PATH/dev-system/ci/scripts/generate-configs.nu \\n  --config .typedialog/ci/config.ncl \\n  --templates $env.TOOLS_PATH/dev-system/ci/templates \\n  --output . \\n  --namespace ci\n```\n\n## Common Tasks\n\n### Add a New Tool\n\nEdit `config.ncl` and add under `ci.tools`:\n\n```\n{\n  ci = {\n    tools = {\n      newtool = {\n        enabled = true,\n        install_method = "cargo",\n        version = "latest",\n      },\n    },\n  },\n}\n```\n\n### Disable a Feature\n\n```\n[ci.features]\nenable_pre_commit = false\n```\n\n## Need Help?\n\nFor detailed documentation, see:\n\n- $env.TOOLS_PATH/dev-system/ci/docs/configuration-guide.md\n- $env.TOOLS_PATH/dev-system/ci/docs/installation-guide.md
