# Fragments\n\nReusable form fragments organized FLAT in this directory (not nested subdirectories).\n\n## Purpose\n\nFragments provide:\n- **Reusable sections** - Used by multiple forms\n- **Modularity** - Change once, applies to all forms using it\n- **Organization** - Named by purpose (workspace, server, queue, etc.)\n- **DRY principle** - Don't repeat configuration sections\n\n## Fragment Organization\n\n**CRITICAL**: All fragments are stored at the SAME LEVEL (flat directory).\n\n```\nfragments/\n├── workspace-section.toml              # Workspace configuration\n├── server-section.toml                 # HTTP server settings\n├── database-rocksdb-section.toml       # RocksDB database\n├── database-surrealdb-section.toml     # SurrealDB database\n├── database-postgres-section.toml      # PostgreSQL database\n├── security-section.toml               # Auth, RBAC, encryption\n├── monitoring-section.toml             # Metrics, health checks\n├── logging-section.toml                # Log configuration\n├── orchestrator-queue-section.toml     # Orchestrator queue config\n├── orchestrator-workflow-section.toml  # Orchestrator batch workflow\n├── orchestrator-storage-section.toml   # Orchestrator storage backend\n├── control-center-jwt-section.toml     # Control Center JWT\n├── control-center-rbac-section.toml    # Control Center RBAC\n├── control-center-compliance-section.toml\n├── mcp-capabilities-section.toml       # MCP capabilities\n├── mcp-tools-section.toml              # MCP tools configuration\n├── mcp-resources-section.toml          # MCP resource limits\n├── deployment-mode-section.toml        # Deployment mode selection\n├── resources-section.toml              # Resource allocation (CPU, RAM, disk)\n└── README.md                           # This file\n```\n\nReferenced in forms as:\n```\n[[items]]\nname = "workspace_group"\ntype = "group"\nincludes = ["fragments/workspace-section.toml"]  # Flat reference\n\n[[items]]\nname = "queue_group"\ntype = "group"\nincludes = ["fragments/orchestrator-queue-section.toml"]  # Same level\n```\n\n## Fragment Categories\n\n### Common Fragments (Used by Multiple Services)\n\n- **workspace-section.toml** - Workspace name, path, enable/disable\n- **server-section.toml** - HTTP server host, port, workers, keep-alive\n- **database-rocksdb-section.toml** - RocksDB path (filesystem-backed)\n- **database-surrealdb-section.toml** - SurrealDB embedded (no external service)\n- **database-postgres-section.toml** - PostgreSQL server connection\n- **security-section.toml** - JWT issuer, RBAC, encryption keys\n- **monitoring-section.toml** - Metrics interval, health checks\n- **logging-section.toml** - Log level, format, rotation\n- **resources-section.toml** - CPU cores, memory, disk allocation\n- **deployment-mode-section.toml** - Solo/MultiUser/CI/CD/Enterprise selection\n\n### Service-Specific Fragments\n\n**Orchestrator** (workflow engine):\n- **orchestrator-queue-section.toml** - Max concurrent tasks, retries, timeout\n- **orchestrator-workflow-section.toml** - Batch workflow settings, parallelism\n- **orchestrator-storage-section.toml** - Storage backend selection\n\n**Control Center** (policy/RBAC):\n- **control-center-jwt-section.toml** - JWT issuer, audience, token expiration\n- **control-center-rbac-section.toml** - Roles, permissions, policies\n- **control-center-compliance-section.toml** - SOC2, HIPAA, audit logging\n\n**MCP Server** (protocol):\n- **mcp-capabilities-section.toml** - Tools, prompts, resources, sampling\n- **mcp-tools-section.toml** - Tool timeout, max concurrent, categories\n- **mcp-resources-section.toml** - Max size, caching, TTL\n\n## Fragment Structure\n\nEach fragment is a TOML file containing `[[elements]]` definitions:\n\n```\n# fragments/workspace-section.toml\n\n[[elements]]\nborder_top = true\nborder_bottom = true\nname = "workspace_header"\ntitle = "🗂️ Workspace Configuration"\ntype = "section_header"\n\n[[elements]]\nname = "workspace_name"\ntype = "text"\nprompt = "Workspace Name"\ndefault = "default"\nrequired = true\nhelp = "Name of the workspace this service will serve"\nnickel_path = ["orchestrator", "workspace", "name"]\n\n[[elements]]\nname = "workspace_path"\ntype = "text"\nprompt = "Workspace Path"\ndefault = "/var/lib/provisioning/orchestrator"\nrequired = true\nhelp = "Absolute path to the workspace directory"\nnickel_path = ["orchestrator", "workspace", "path"]\n\n[[elements]]\nname = "workspace_enabled"\ntype = "confirm"\nprompt = "Enable Workspace?"\ndefault = true\nhelp = "Enable or disable this workspace"\nnickel_path = ["orchestrator", "workspace", "enabled"]\n```\n\n## Fragment Composition\n\nFragments are included in main forms:\n\n```\n# forms/orchestrator-form.toml\n\nname = "orchestrator_configuration"\ndescription = "Interactive configuration for Orchestrator"\n\n# Include fragments in order\n\n[[items]]\nname = "deployment_group"\ntype = "group"\nincludes = ["fragments/deployment-mode-section.toml"]\n\n[[items]]\nname = "workspace_group"\ntype = "group"\nincludes = ["fragments/workspace-section.toml"]\n\n[[items]]\nname = "server_group"\ntype = "group"\nincludes = ["fragments/server-section.toml"]\n\n[[items]]\nname = "storage_group"\ntype = "group"\nincludes = ["fragments/orchestrator-storage-section.toml"]\n\n[[items]]\nname = "queue_group"\ntype = "group"\nincludes = ["fragments/orchestrator-queue-section.toml"]\n\n# Optional sections\n[[items]]\nname = "monitoring_group"\ntype = "group"\nwhen = "enable_monitoring == true"\nincludes = ["fragments/monitoring-section.toml"]\n```\n\n## Element Requirements\n\nEvery element in a fragment MUST include:\n\n1. **name** - Unique identifier (used in form data)\n2. **type** - Element type (text, number, confirm, select, etc.)\n3. **prompt** - User-facing label\n4. **nickel_path** - Mapping to Nickel structure (**CRITICAL**)\n\nExample:\n```\n[[elements]]\nname = "max_concurrent_tasks"          # Unique identifier\ntype = "number"                        # Type\nprompt = "Maximum Concurrent Tasks"    # User label\nnickel_path = ["orchestrator", "queue", "max_concurrent_tasks"]  # Nickel mapping\n```\n\n## Constraint Interpolation\n\nFragments reference constraints dynamically:\n\n```\n[[elements]]\nname = "max_concurrent_tasks"\ntype = "number"\nprompt = "Maximum Concurrent Tasks"\nmin = "${constraint.orchestrator.queue.concurrent_tasks.min}"  # Dynamic\nmax = "${constraint.orchestrator.queue.concurrent_tasks.max}"  # Dynamic\nnickel_path = ["orchestrator", "queue", "max_concurrent_tasks"]\n```\n\nThe `${constraint.path.to.value}` syntax references `constraints/constraints.toml`.\n\n## Common Fragment Patterns\n\n### Workspace Fragment Pattern\n```\n[[elements]]\nname = "workspace_name"\ntype = "text"\nprompt = "Workspace Name"\nnickel_path = ["orchestrator", "workspace", "name"]\n\n[[elements]]\nname = "workspace_path"\ntype = "text"\nprompt = "Workspace Path"\nnickel_path = ["orchestrator", "workspace", "path"]\n\n[[elements]]\nname = "workspace_enabled"\ntype = "confirm"\nprompt = "Enable Workspace?"\nnickel_path = ["orchestrator", "workspace", "enabled"]\n```\n\n### Server Fragment Pattern\n```\n[[elements]]\nname = "server_host"\ntype = "text"\nprompt = "Server Host"\ndefault = "127.0.0.1"\nnickel_path = ["orchestrator", "server", "host"]\n\n[[elements]]\nname = "server_port"\ntype = "number"\nprompt = "Server Port"\nmin = "${constraint.common.server.port.min}"\nmax = "${constraint.common.server.port.max}"\nnickel_path = ["orchestrator", "server", "port"]\n\n[[elements]]\nname = "server_workers"\ntype = "number"\nprompt = "Worker Threads"\nmin = 1\nmax = 32\nnickel_path = ["orchestrator", "server", "workers"]\n```\n\n### Database Selection Pattern\n```\n[[elements]]\nname = "storage_backend"\ntype = "select"\nprompt = "Storage Backend"\noptions = [\n  { value = "filesystem", label = "📁 Filesystem" },\n  { value = "rocksdb", label = "🗄️ RocksDB (Embedded)" },\n  { value = "surrealdb", label = "📊 SurrealDB" },\n  { value = "postgres", label = "🐘 PostgreSQL" },\n]\nnickel_path = ["orchestrator", "storage", "backend"]\n\n[[elements]]\nname = "rocksdb_group"\ntype = "group"\nwhen = "storage_backend == 'rocksdb'"\nincludes = ["fragments/database-rocksdb-section.toml"]\n\n[[elements]]\nname = "postgres_group"\ntype = "group"\nwhen = "storage_backend == 'postgres'"\nincludes = ["fragments/database-postgres-section.toml"]\n\n[[elements]]\nname = "surrealdb_group"\ntype = "group"\nwhen = "storage_backend == 'surrealdb'"\nincludes = ["fragments/database-surrealdb-section.toml"]\n```\n\n## Best Practices\n\n1. **Clear naming** - Fragment name describes its purpose (queue-section, not qs)\n2. **Meaningful headers** - Each fragment starts with a section header (name, title, emoji)\n3. **Constraint interpolation** - Use `${constraint.*}` for dynamic validation\n4. **Consistent nickel_path** - Paths match actual Nickel structure\n5. **Provide defaults** - Sensible defaults improve UX\n6. **Help text** - Explain each field clearly\n7. **Group logically** - Related fields in same fragment\n8. **Test with form** - Verify fragment loads correctly in form\n\n## Adding a New Fragment\n\n1. **Create fragment file** in `forms/fragments/{name}-section.toml`\n2. **Add section header** (name, title, emoji)\n3. **Add form elements**:\n   - Include `name`, `type`, `prompt`\n   - Add `nickel_path` (CRITICAL)\n   - Add constraints if applicable\n   - Add `help` and `default` if appropriate\n4. **Include in form** - Add to main form via `includes` field\n5. **Test** - Run configuration wizard to verify fragment loads\n\n## Fragment Naming Convention\n\n- **Section fragments**: `{topic}-section.toml` (workspace-section.toml)\n- **Service-specific**: `{service}-{topic}-section.toml` (orchestrator-queue-section.toml)\n- **Database-specific**: `database-{backend}-section.toml` (database-postgres-section.toml)\n- **Deployment-specific**: `{mode}-{topic}-section.toml` (enterprise-options-section.toml)\n\n## Testing Fragments\n\n```\n# Validate form that uses fragment\nnu provisioning/.typedialog/provisioning/platform/scripts/configure.nu orchestrator solo --backend web\n\n# Verify constraint interpolation works\ngrep "constraint\." forms/fragments/*.toml\n\n# Check nickel_path consistency\ngrep "nickel_path" forms/fragments/*.toml | sort\n```\n\n---\n\n**Version**: 1.0.0\n**Last Updated**: 2025-01-05
