docs(cli): add ABsmartly CLI documentation (FT-2052)

docs/APIs-and-SDKs/CLI-Documentation/_category_.json

@@ -0,0 +1,6 @@
+{
+  "position": 5,
+  "collapsible": true,
+  "collapsed": true,
+  "label": "CLI Documentation"
+}

docs/APIs-and-SDKs/CLI-Documentation/authentication.mdx

@@ -0,0 +1,89 @@
+---
+sidebar_position: 2
+---
+
+# Authentication
+
+The CLI stores credentials in your OS keychain (via keytar) and configuration in `~/.config/absmartly/config.yaml`. On headless systems without a keychain service, credentials fall back to `~/.config/absmartly/credentials.json` (chmod 600).
+
+Two authentication methods are supported.
+
+## API key authentication
+
+```bash
+# Login with API key
+abs auth login --api-key YOUR_KEY --endpoint https://your-instance.absmartly.com/v1
+
+# Login with a named profile
+abs auth login --api-key YOUR_KEY --endpoint https://staging.absmartly.com/v1 --profile staging
+```
+
+## OAuth authentication
+
+When no `--api-key` is provided, the CLI launches an OAuth browser flow. After authorization, it can either create a persistent API key (default) or use session-based JWT tokens.
+
+```bash
+# OAuth login (opens browser, creates persistent API key)
+abs auth login --endpoint https://your-instance.absmartly.com/v1
+
+# OAuth with session-based JWT tokens (no persistent key, expires in 24h)
+abs auth login --endpoint https://your-instance.absmartly.com/v1 --session
+
+# Skip prompt and always create persistent API key
+abs auth login --endpoint https://your-instance.absmartly.com/v1 --persistent
+
+# Headless environments (print URL instead of opening browser)
+abs auth login --endpoint https://your-instance.absmartly.com/v1 --no-browser
+
+# Allow self-signed TLS certificates
+abs auth login --endpoint https://dev.local/v1 -k
+```
+
+:::warning Security note
+The `-k` flag disables TLS certificate verification. Only use in trusted development environments.
+:::
+
+## Auth commands
+
+```bash
+# Check authentication status
+abs auth status
+abs auth status --show-key    # reveal full API key
+abs auth status --profile staging
+
+# Show current authenticated user
+abs auth whoami
+abs auth whoami --avatar       # display avatar inline (iTerm2, Kitty, Sixel)
+abs auth whoami --avatar 30    # avatar at 30 columns wide
+
+# Manage personal API keys
+abs auth list-api-keys
+abs auth create-api-key --name "CI Key" --description "For CI/CD pipelines"
+abs auth get-api-key 1
+abs auth update-api-key 1 --name "Renamed Key"
+abs auth delete-api-key 1
+
+# Edit your profile
+abs auth edit-profile --first-name "Jonas" --last-name "Alves" --department "Engineering"
+
+# Change your own password
+abs auth reset-my-password
+
+# Logout
+abs auth logout
+abs auth logout --profile staging
+```
+
+You can also override credentials per-command with global options:
+
+```bash
+abs experiments list --api-key YOUR_KEY --endpoint https://your-instance.absmartly.com/v1
+```
+
+## Credential resolution order
+
+`--api-key` flag > `ABSMARTLY_API_KEY` env > OS keychain > `~/.config/absmartly/credentials.json`
+
+:::warning Security note
+Environment variables may be visible in process listings and logs. For production, prefer OS keychain storage (default) or the credentials file on headless systems.
+:::

docs/APIs-and-SDKs/CLI-Documentation/configuration.mdx

@@ -0,0 +1,110 @@
+---
+sidebar_position: 3
+---
+
+# Global Options & Configuration
+
+## Global options
+
+These options are available on every command:
+
+| Option | Description |
+|---|---|
+| `--config <path>` | Config file path |
+| `--api-key <key>` | Override API key |
+| `--endpoint <url>` | Override API endpoint |
+| `--app <name>` | Override default application |
+| `--env <name>` | Override default environment |
+| `-o, --output <format>` | Output format: `table` (default), `json`, `yaml`, `plain`, `markdown`, `rendered`, `vertical`, `template` |
+| `--no-color` | Disable colored output |
+| `-v, --verbose` | Verbose output |
+| `-q, --quiet` | Minimal output |
+| `--profile <name>` | Use a specific profile |
+| `--terse` | Compact format with truncation |
+| `--full` | Full text without truncation |
+| `--raw` | Show raw API response without summarizing or transforming |
+
+## Configuration file
+
+Configuration is stored in `~/.config/absmartly/config.yaml` as YAML. API keys are stored securely in your OS keychain via [keytar](https://github.com/atom/node-keytar).
+
+```bash
+# View current configuration
+abs config list
+
+# Get/set individual values
+abs config get output
+abs config set output json
+abs config unset output
+
+# Manage profiles
+abs config profiles list
+abs config profiles use staging
+abs config profiles delete old-profile
+```
+
+### Configuration file format
+
+```yaml
+default-profile: default
+analytics-opt-out: false
+output: table
+profiles:
+  default:
+    api:
+      endpoint: https://your-instance.absmartly.com/v1
+    expctld:
+      endpoint: https://ctl.absmartly.io/v1
+    application: my-app
+    environment: production
+  staging:
+    api:
+      endpoint: https://staging.absmartly.com/v1
+    expctld:
+      endpoint: https://ctl.absmartly.io/v1
+    environment: staging
+```
+
+### Environment variables
+
+| Variable | Description |
+|---|---|
+| `ABSMARTLY_API_KEY` | API key (overrides keychain and credentials file) |
+| `ABSMARTLY_API_ENDPOINT` | API endpoint URL (overrides profile config) |
+
+See [Authentication](./authentication) for the full credential resolution order and OAuth/API key login flows.
+
+## Date formats
+
+All `--from`, `--to`, `--since`, `--created-after`, `--started-before`, and other date/timestamp options across the CLI accept the same formats:
+
+| Format | Example |
+|---|---|
+| Relative (short) | `7d`, `2w`, `1mo`, `24h`, `30m`, `1y` |
+| Relative (with ago) | `7d ago`, `2 weeks ago`, `3 months ago` |
+| Keywords | `today`, `yesterday`, `now` |
+| ISO 8601 date | `2024-01-01` |
+| ISO 8601 datetime | `2024-01-01T00:00:00Z` |
+| Epoch milliseconds | `1704067200000` |
+
+Relative units: `m` (minutes), `h` (hours), `d` (days), `w` (weeks), `mo` (months), `y` (years). Case-insensitive.
+
+Commands using date formats:
+- `abs experiments list --created-after`, `--created-before`, `--started-after`, `--started-before`, `--stopped-after`, `--stopped-before`
+- `abs experiments metrics results --from`, `--to`
+- `abs activity-feed list --since`
+- `abs events list --from`, `--to`
+- `abs events history --from`, `--to`
+- `abs events json-values --from`, `--to`
+- `abs events json-layouts --from`, `--to`
+- `abs insights velocity --from`, `--to` (and `decisions`, `velocity-detail`, `decisions-history`)
+
+```bash
+abs experiments list --created-after 7d                  # last 7 days
+abs experiments list --stopped-after "30 days ago"       # stopped in last month
+abs experiments list --started-after yesterday
+abs experiments list --created-after 2024-01-01          # since Jan 1 2024
+abs experiments metrics results 123 --from 7d --to now
+abs activity-feed list --since 1h
+abs events list --from 2w --to yesterday
+```

docs/APIs-and-SDKs/CLI-Documentation/experiment-templates.mdx

@@ -0,0 +1,115 @@
+---
+sidebar_position: 6
+---
+
+# Experiment Templates
+
+The CLI uses Markdown templates with YAML frontmatter for experiment round-trips. All names (metrics, owners, teams, tags, applications) are resolved by name — no IDs needed.
+
+```bash
+# Generate a blank template
+abs experiments generate-template -o experiment.md
+
+# Export an existing experiment as a template
+abs experiments get 123 -o template > experiment.md
+abs experiments get 123 -o template --embed-screenshots > experiment.md  # with base64 screenshots
+abs experiments get 123 -o template --screenshots-dir ./screenshots      # save screenshots as files
+
+# Create from template
+abs experiments create --from-file experiment.md
+abs experiments create --from-file experiment.md --dry-run   # preview payload
+cat experiment.md | abs experiments create --from-file -     # from stdin
+
+# Update from template
+abs experiments update 123 --from-file experiment.md
+
+# Clone (shortcut)
+abs experiments clone 123 --name my-clone
+
+# Restart with changes
+abs experiments restart 123 --from-file changes.md --reason hypothesis_iteration
+```
+
+## Template format
+
+````markdown
+---
+name: my_experiment
+display_name: "My Experiment"
+unit_type: user_id
+application: www
+primary_metric: Net conversion rate
+secondary_metrics:
+  - Gross conversion rate
+  - Product page views
+guardrail_metrics:
+  - Page load time (ms)
+  - Error rate
+percentages: 50/50
+percentage_of_traffic: 100
+owners:
+  - Márcio Martins <marcio@absmartly.com>
+  - Cal Courtney <cal@absmartly.com>
+teams:
+  - Product
+  - Engineering
+tags:
+  - q1
+  - homepage
+analysis_type: group_sequential
+required_alpha: 0.1
+required_power: 0.8
+baseline_participants: 143
+---
+
+## Audience
+
+```json
+{
+  "filter": [
+    { "and": [{ "eq": [{ "var": { "path": "language" } }, { "value": "en-GB" }] }] }
+  ]
+}
+```
+
+## Variants
+
+### variant_0
+
+name: Control
+config: {}
+![Control variant](./screenshots/control.png)
+
+### variant_1
+
+name: Treatment
+config: {"feature_enabled": true}
+![Treatment variant](./screenshots/treatment.png)
+
+## Description
+
+### Hypothesis
+
+We believe changing X will improve Y by Z%.
+
+### Implementation Details
+
+Details here...
+
+## JIRA
+
+### JIRA URL
+
+https://jira.example.com/IT-1234
+````
+
+## Template features
+
+- **Metrics**: resolved by name, including archived metrics
+- **Owners**: `Name <email>`, email, or user ID
+- **Teams/tags**: resolved by name
+- **Audience**: JSON code block, parsed and compacted for the API
+- **Custom fields**: grouped by section name (matches UI sections)
+- **User-type fields**: exported as email, converted back to `{"selected":[{"userId":N}]}`
+- **Screenshots**: local file paths, URLs, or base64 data URIs
+- **Type**: inferred from command (`abs experiments` → test, `abs features` → feature)