@profoundlogic/coderflow-server 0.2.1

package/dist/web-ui/public/docs/admin/installation.md

@@ -0,0 +1,313 @@
+# Installation
+
+This guide walks you through setting up a CoderFlow server.
+
+## Prerequisites
+
+A Linux server with the following installed:
+
+- **Docker** — [Install Docker Engine](https://docs.docker.com/engine/install/)
+- **Git** — Available via your distribution's package manager
+
+Optionally, if you'd like the server to listen on a port below 1024 (such as 443 or 80):
+
+- **On Ubuntu and Debian-based distros** - Install [authbind](https://manpages.ubuntu.com/manpages/noble/man1/authbind.1.html) via APT package manager.
+- **Other distros** - See your distro's documentation for enabling non-root users to bind network services to privileged ports
+
+## Root Permissions
+
+> [!IMPORTANT]
+> Only a few parts of the installation process require root permissions.  
+> Do not use root permissions (i.e. `sudo` or `su`) except where specifically instructed.  
+> The server installs and runs as a non-root user.
+
+## Create a Dedicated Linux User For Each Installation
+
+Each installation of CoderFlow server should run under a unique and dedicated user account, rather than your personal account or root. This provides better security isolation and makes it easier to manage the service.
+
+Create a dedicated user (we suggest `coder`, but any name works):
+
+```bash
+# Create the user with a home directory
+sudo useradd -m -s /bin/bash coder
+
+# Set a password (optional, if you need interactive login)
+sudo passwd coder
+
+# Add the user to the docker group so it can manage containers
+sudo usermod -aG docker coder
+```
+
+If `coder` conflicts with an existing user on your system, choose a different name — the server works the same regardless of the username.
+
+## Optional: If Using Server Listen Port Below 1024
+
+If you'd like to use a server listen port below 1024 (e.g. 443), configure `authbind` to allow the dedicated CoderFlow user to use the port:
+
+For example, for port 443:
+
+```bash
+sudo touch /etc/authbind/byport/443
+sudo chown coder /etc/authbind/byport/443
+sudo chmod 500 /etc/authbind/byport/443
+```
+
+## Switch to Dedicated CoderFlow User
+
+Switch to the dedicated user before proceeding with installation:
+
+```bash
+sudo su - coder
+```
+
+## Install Node.js via NVS
+
+Use the [installation guide](https://github.com/jasongin/nvs?tab=readme-ov-file#mac-linux) to install Node Version Switcher (NVS) in the dedicated user's home directory. This allows each CoderFlow installation/user to use a separate version of Node.js.  If you prefer, you can use `nvm` instead, but NVS will be used in this documentation.
+
+After installing NVS, exit and restart your shell and then install Node 24:
+
+```bash
+nvs add node/24
+nvs use node/24
+nvs link node/24
+```
+
+## Setup
+
+### Install the Server
+
+```bash
+npm install -g @profoundlogic/coderflow-server
+```
+
+### Create a Setup Repository
+
+The setup repository contains your environments, task templates, and configuration.
+
+If your organization already has a setup repository, clone it:
+
+```bash
+git clone https://github.com/your-org/mycompany-coder-setup.git
+```
+
+Otherwise, create a new one:
+
+```bash
+coder-server init mycompany-coder-setup
+```
+
+This creates a `mycompany-coder-setup` directory with the required structure and initializes it as a git repository.
+
+### Install License
+
+```bash
+coder-server license set <your-license-key> --setup-path=mycompany-coder-setup
+```
+
+### Create Admin User
+
+```bash
+coder-server create-user --username=admin --email=admin@example.com --name="Admin User" --role=admin
+```
+
+You'll be prompted to set a password.
+
+### Optional: Configure Server Listen Port and SSL
+
+By default the server listens on port 3000. To configure an alternate port (e.g. 443):
+
+```bash
+coder-server config set server_port 443
+```
+
+To configure a certificate for SSL:
+
+> [!INFO]
+> Certificate and key files must be in PEM format.  
+> Concatenate certificate, intermediate, and root into a single file, in that order.  
+> File paths can be given as absolute or relative.  
+> Files must be readable by the dedicated CoderFlow user.
+
+```bash
+coder-server config set ssl_cert_path mycert.pem
+coder-server config set ssl_key_path mykey.pem
+```
+
+### Start the Server
+
+```bash
+coder-server start
+```
+
+If using a listen port below 1024 (e.g. 443, 80) and using `authbind` to allow that, the server must be started like this instead:
+
+```bash
+authbind --deep coder-server start
+```
+
+Once running, log in to the Web UI (default port 3000) with the admin user you created.
+
+## Set Up Git Providers
+
+To allow CoderFlow access to your Git hosting service (e.g., GitHub), follow the instructions in [Git Providers](admin/git-providers.md).
+
+## Configure Your Environment
+
+The `coder-server init` command created a default environment with placeholder values. Configure it through the Web UI:
+
+1. Navigate to **Environments** in the Web UI
+2. Click on the **default** environment, if it isn't already selected
+3. Update each section:
+
+### Repos
+
+Click **Add Repository** to add your GitHub repository:
+- **Git Provider**: Choose a Git provider from the list
+- **URL**: URL (e.g., `https://github.com/acme/my-project.git`)
+- **Branch**: Default branch (e.g., `main`)
+
+## Build Docker Images
+
+Docker images must be built before you can run tasks. There are two ways to build images: through the Web UI or using the CLI.
+
+### Build Base Image
+
+Build the base image that all environments inherit from.
+
+**Web UI:**
+1. Navigate to **Settings → Environments**
+2. Select your environment, if it's not already selected
+3. Click **Actions → Build Base Image**
+4. Optionally check "Build without cache" for a clean rebuild
+5. Click **Build**
+
+**CLI:**
+```bash
+coder-server build base
+```
+
+### Build Environment Image
+
+Build your environment's Docker image.
+
+**Web UI:**
+1. Navigate to **Settings → Environments**
+2. Select your environment, if it's not already selected
+3. Go to the **Build** tab
+4. Click **Build Now**
+
+**CLI:**
+```bash
+coder-server build default
+```
+
+Rebuild after making changes to the Dockerfile or setup.sh.
+
+## Set Up LLM Access
+
+Before running tasks, configure access to AI providers. Authentication can be performed by both OAuth and API keys.
+
+To authenticate task execution using your subscription accounts (OAuth), follow the instructions in [AI Provider Authentication](admin/ai-providers.md).
+
+Authentication using AI keys can be used for task execution as well as auto-generating task names. To authenticate using AI keys, do the following:
+
+1. Navigate to **Settings → Server Settings → API Keys** in the Web UI
+2. For each provider, enter the corresponding API key (the default agent's API key will be used when auto-generating task names)
+3. To execute tasks for a provider using API keys, switch its toggle on
+
+Supported providers:
+- **Claude** (Anthropic)
+- **Codex** (OpenAI)
+- **Gemini** (Google)
+
+## Verify Installation
+
+The best way to verify everything works is to submit a task:
+
+1. Open the Web UI in your browser
+2. Select your environment and enter a simple task (e.g., "List the files in the repository")
+3. Submit and watch the task run
+
+If the task completes successfully, your installation is working.
+
+## Server Management
+
+### Running as a Daemon
+
+Use the `--daemon` flag to run the server in the background:
+
+```bash
+coder-server start --daemon
+```
+
+Manage the daemon with:
+
+```bash
+# View logs
+coder-server logs
+
+# Stop server
+coder-server stop
+
+# Restart
+coder-server restart
+
+# Check health
+curl http://your-server:3000/health
+```
+
+### Using PM2
+
+As an alternative to the built-in daemon mode, you can use [PM2](https://pm2.keymetrics.io/) for process management.
+
+PM2 provides additional features like automatic restarts on crash and system boot persistence.
+
+#### Install PM2 Globally
+
+```bash
+npm install -g pm2
+```
+
+#### Start CoderFlow with PM2
+
+If using a listen port below 1024 (e.g. 443, 80) and using `authbind` to allow that, the server must be started like this:
+
+```bash
+pm2 start --name coderflow authbind -- --deep coder-server start
+```
+
+Otherwise start like this:
+
+```bash
+pm2 start --name coderflow coder-server -- start
+```
+
+#### View Logs
+
+```bash
+pm2 logs coderflow
+```
+
+#### Stop/Restart
+
+```bash
+pm2 stop coderflow
+pm2 start coderflow
+pm2 restart coderflow
+```
+
+#### Auto-start On System Boot
+
+Save the PM2 process list to disk:
+
+```bash
+pm2 save
+```
+
+Generate a PM2 startup script:
+
+```bash
+pm2 startup
+```
+
+`pm2 startup` outputs a commmand string to your terminal, which must be run as root, to configure the system's service manager to start up PM2 at system boot.

package/dist/web-ui/public/docs/admin/skills.md

@@ -0,0 +1,35 @@
+# Skills
+
+Skills are reusable, prompt-based actions that agents can invoke during tasks. Each skill lives in your coder setup repository under `skills/<skill-id>/` with a `SKILL.md` file and optional supporting files (templates, scripts, references).
+
+## Managing Skills
+
+Open **Administration -> Skills** in the Web UI to create and manage skills. The Skills page includes the same git workflow as environments:
+
+- **Save** changes without committing
+- **Commit & Push** to version skills in your coder setup repository
+- **Pull** and **Discard** to sync with teammates
+
+### Create or Edit Skills
+
+Use **New Skill** to create a skill ID, display name, and description. Each skill includes:
+
+- **Metadata** (name, description, model/tools hints)
+- **Prompt** (the instructions in `SKILL.md`)
+- **Supporting Files** (optional files referenced by the prompt)
+
+### Import External Skills
+
+You can also import skills from external sources:
+
+- **Catalog** — curated skills bundled with CoderFlow
+- **Git repository** — import a skill directory from a repo
+- **Local folder** — import from a path on the server
+
+Imported skills stay synced with their source. Git-based imports can be updated from the Skills page when updates are available.
+
+## Assign Skills to Environments
+
+Skills become available to agents only after they are assigned to an environment. In **Environments -> Overview**, click **Add Skills** and select the skills to include. The selected skills propagate to every new task launched in that environment.
+
+If you update skill assignments, save the environment and launch a new task for the changes to take effect.

package/dist/web-ui/public/docs/admin/sso.md

@@ -0,0 +1,241 @@
+# Single Sign-On (SSO)
+
+CoderFlow supports Single Sign-On via OpenID Connect (OIDC), allowing users to authenticate with your organization's identity provider.
+
+## Overview
+
+SSO provides:
+
+- **Centralized authentication** — Users log in with existing corporate credentials
+- **Automatic user provisioning** — New users are created on first login
+- **Security compliance** — Leverage your IdP's MFA, conditional access, and audit logging
+
+CoderFlow works with any OIDC-compliant identity provider, including Microsoft Entra ID, Okta, Google Workspace, and Auth0.
+
+## VS Code Extension
+
+When SSO is enabled, the VS Code extension profile manager shows a **Sign in with SSO** option. The extension opens a browser window to complete the SSO flow, then exchanges the approved session for an API key to store in the profile. This works even if local username/password login is disabled.
+
+## Configuration Methods
+
+SSO can be configured in two ways:
+
+- **Web UI** — Configure through the Settings page (recommended)
+- **Configuration file** — Edit `oidc.json` directly in your setup repository
+
+Both methods produce the same result. The Web UI is recommended for most users as it provides validation and a guided setup experience.
+
+## Configuring via Web UI
+
+1. Navigate to **Settings → Single Sign-On**
+2. Configure the **Connection** tab:
+   - Enable SSO
+   - Select your identity provider (or Custom for other providers)
+   - Enter your Client ID, Client Secret, and Issuer URL
+   - Use **Test Connection** to verify your settings
+5. Configure the **User Provisioning** tab:
+   - Enable/disable auto-provisioning
+   - Set the default role for new users
+   - Choose whether to allow local login alongside SSO
+6. Click **Save** to save and apply changes immediately
+
+## Configuring via File
+
+Create an `oidc.json` file in your setup repository root:
+
+```json
+{
+  "enabled": true,
+  "display_name": "Sign in with Microsoft",
+  "client_id": "your-client-id",
+  "client_secret": "your-client-secret",
+  "issuer": "https://login.microsoftonline.com/{tenant-id}/v2.0",
+  "scopes": ["openid", "profile", "email"],
+  "auto_provision": true,
+  "default_role": "developer",
+  "allow_local_auth": true
+}
+```
+
+After saving the file, restart CoderFlow or use the Web UI to reload the configuration.
+
+> **Security Note**: The `oidc.json` file contains secrets and is automatically excluded from git via `.gitignore`.
+
+### Configuration Reference
+
+| Option | Required | Default | Description |
+|--------|----------|---------|-------------|
+| `enabled` | Yes | — | Set to `true` to enable SSO |
+| `display_name` | No | `"Sign in with SSO"` | Text displayed on the SSO button |
+| `client_id` | Yes | — | Application/client ID from your identity provider |
+| `client_secret` | Yes | — | Client secret from your identity provider |
+| `issuer` | Yes | — | OIDC issuer URL (used for discovery) |
+| `scopes` | No | `["openid", "profile", "email"]` | OAuth scopes to request |
+| `auto_provision` | No | `true` | Automatically create users on first SSO login |
+| `default_role` | No | `"developer"` | Role assigned to auto-provisioned users |
+| `allow_local_auth` | No | `true` | Show local login form alongside SSO button |
+
+## Microsoft Entra ID Setup
+
+### 1. Create App Registration
+
+1. Go to [Azure Portal](https://portal.azure.com)
+2. Navigate to **Microsoft Entra ID** > **App registrations** > **New registration**
+3. Configure the registration:
+   - **Name**: `CoderFlow` (or your preferred name)
+   - **Supported account types**: Single tenant (recommended for enterprise)
+   - **Redirect URI**: Select **Web** and enter `https://{your-coderflow-host}/auth/oidc/callback`
+4. Click **Register**
+5. Note the **Application (client) ID** and **Directory (tenant) ID** from the Overview page
+
+### 2. Create Client Secret
+
+1. In your app registration, go to **Certificates & secrets**
+2. Click **New client secret**
+3. Add a description and select an expiration period
+4. Click **Add**
+5. Copy the secret **Value** immediately (it won't be shown again)
+
+### 3. Configure CoderFlow
+
+**Via Web UI:**
+1. Go to **Settings → Single Sign-On**
+2. Select **Microsoft Entra ID (Azure AD)** as the provider
+3. Enter your Client ID and Client Secret
+4. Replace `{tenant-id}` in the Issuer URL with your Directory (tenant) ID
+5. Click **Save**
+
+**Via configuration file:**
+
+Create `oidc.json` in your setup repository:
+
+```json
+{
+  "enabled": true,
+  "display_name": "Sign in with Microsoft",
+  "client_id": "{your-application-client-id}",
+  "client_secret": "{your-client-secret-value}",
+  "issuer": "https://login.microsoftonline.com/{your-tenant-id}/v2.0",
+  "scopes": ["openid", "profile", "email"],
+  "auto_provision": true,
+  "default_role": "developer",
+  "allow_local_auth": true
+}
+```
+
+## Other Identity Providers
+
+### Okta
+
+**Issuer URL:** `https://{your-okta-domain}/oauth2/default`
+
+In Okta Admin Console:
+1. Create a new **Web** application
+2. Set the redirect URI to `https://{your-coderflow-host}/auth/oidc/callback`
+3. Copy the Client ID and Client Secret
+
+### Google Workspace
+
+**Issuer URL:** `https://accounts.google.com`
+
+In Google Cloud Console:
+1. Create OAuth 2.0 credentials (Web application type)
+2. Add `https://{your-coderflow-host}/auth/oidc/callback` to authorized redirect URIs
+3. Copy the Client ID and Client Secret
+
+### Generic OIDC Provider
+
+For other OIDC-compliant providers, you need:
+
+- **Issuer URL**: Must support OIDC discovery (`.well-known/openid-configuration`)
+- **Client ID and Secret**: From your provider's application registration
+- **Redirect URI**: `https://{your-coderflow-host}/auth/oidc/callback`
+
+## User Provisioning
+
+### Auto-Provisioning Enabled (Default)
+
+When auto-provisioning is enabled, CoderFlow automatically creates a user account on first SSO login:
+
+- **Username**: Derived from email (e.g., `john.doe@company.com` becomes `johndoe`)
+- **Email**: From the identity provider's claims
+- **Name**: From the identity provider's claims
+- **Role**: Set to the configured default role (defaults to `developer`)
+
+The user can immediately access CoderFlow based on their assigned role.
+
+### Auto-Provisioning Disabled
+
+When auto-provisioning is disabled, users must be created in CoderFlow before they can log in via SSO. Create users with matching email addresses:
+
+```bash
+coder-server create-user --username=johndoe --email=john.doe@company.com --name="John Doe" --role=developer
+```
+
+SSO login will fail with "user not found" if no matching user exists.
+
+### Updating User Information
+
+When an existing user logs in via SSO, CoderFlow updates their display name if it changed in the identity provider. Other fields (username, role, permissions) are managed within CoderFlow.
+
+## SSO-Only Mode
+
+To enforce SSO and hide the local login form, disable "Allow local login" in the Web UI or set `allow_local_auth` to `false` in the configuration file.
+
+> **Important**: Ensure at least one admin user can authenticate via SSO before disabling local auth. If locked out, re-enable local auth through the configuration file and restart the server.
+
+## Removing SSO
+
+To disable SSO:
+
+**Via Web UI:**
+1. Go to **Settings → Single Sign-On**
+2. Click **Remove SSO**
+
+**Via file:**
+Delete the `oidc.json` file from your setup repository and restart CoderFlow.
+
+## Troubleshooting
+
+### "Redirect URI mismatch" Error
+
+The redirect URI in your identity provider must exactly match CoderFlow's callback URL:
+
+```
+https://{your-host}/auth/oidc/callback
+```
+
+Common issues:
+- HTTP vs HTTPS mismatch
+- Missing or extra trailing slash
+- Wrong port number
+- Hostname mismatch (e.g., `localhost` vs `127.0.0.1`)
+
+### "Invalid or expired state" Error
+
+This occurs when:
+- The login took too long (over 10 minutes)
+- The user refreshed the page during login
+- Browser cookies are blocked
+
+Solution: Return to the login page and try again.
+
+### "User not found" Error
+
+This appears when auto-provisioning is disabled and no user with the SSO email exists in CoderFlow. Either:
+- Enable auto-provisioning, or
+- Create the user manually with the correct email address
+
+### "Missing email claim" Error
+
+The identity provider isn't returning the user's email. Ensure:
+- The `email` scope is included in your configuration
+- The user has an email address in the identity provider
+- The app registration has permission to read email (check API permissions in Azure)
+
+### SSO Button Not Appearing
+
+Verify that:
+- SSO is enabled in the configuration
+- The server has loaded the configuration (check server logs)
+- Use **Test Connection** in the Web UI to verify the issuer URL is accessible

package/dist/web-ui/public/docs/admin/users-and-roles.md

@@ -0,0 +1,57 @@
+# Users & Roles
+
+CoderFlow includes role-based access control with four predefined roles. Administrators manage users through the Web UI.
+
+## Roles
+
+### Administrator
+
+Full system access. Administrators can:
+- Manage all users, roles, and permissions
+- Configure environments and system settings
+- Access all tasks across the organization
+- View audit logs and server health
+
+### Manager
+
+Team oversight and task management. Managers can:
+- Create and manage users (up to Manager level)
+- View and manage all tasks
+- Judge, approve, or reject tasks
+- Assign tasks to other users
+
+### Developer
+
+Standard permissions for development work. Developers can:
+- Create and execute tasks
+- View and manage their own tasks
+- Access environments for development
+- Manage their own API keys
+
+### Viewer
+
+Read-only access for monitoring. Viewers can:
+- View their own tasks (read-only)
+- View environment details
+- Manage their own API keys
+
+## Role Hierarchy
+
+Users can only manage others at or below their privilege level:
+- Administrators can manage anyone
+- Managers can manage Developers and Viewers
+- Developers and Viewers cannot manage other users
+
+## Custom Permissions
+
+Beyond role-based permissions, administrators can assign additional permissions to individual users. This allows fine-tuned access control—for example, granting a Developer the ability to judge tasks without promoting them to Manager.
+
+## Managing Users
+
+User management is done through the Web UI:
+- Create new users with username, email, and role
+- Edit user details and change roles
+- Assign custom permissions as needed
+- Deactivate or remove users
+
+For initial setup or automation, users can also be created via command-line scripts or the REST API.