root/fusion
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(FN-3014): document research recovery semantics

Browse Source 
Documents research recovery semantics in the CLI reference and settings reference, adding 9 lines of documentation across both files.

Fusion-Task-Id: FN-3014
This commit is contained in:
Fusion
2026-05-04 08:03:34 -07:00
committed by gsxdsm
parent 815031baf4
commit f1ee69e59a
20 changed files with 631 additions and 61 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
docs/cli-reference.md
View File

@@ -69,12 +69,14 @@ fn research retry RR-001 --json
| `fn research show <run-id> [--json]` | Show one run with timestamps, summary, and error details. |
| `fn research export <run-id> [--format <json\|markdown\|pdf>] [--output <path>] [--json]` | Export run results and persist an export record. |
| `fn research cancel <run-id> [--json]` | Request cancellation for an active run. |
| `fn research retry <run-id> [--json]` | Create a new retry run from a failed/cancelled run. |
| `fn research retry <run-id> [--json]` | Create a new retry run from a `failed`/`timed_out` run when lifecycle marks it retryable. |
Disabled/setup behavior mirrors dashboard and agent surfaces:
- Feature disabled → `FEATURE_DISABLED` (enable project/global research settings)
- Missing credentials → `MISSING_CREDENTIALS` (configure provider auth)
- Provider unavailable or cooldown/rate limit → `PROVIDER_UNAVAILABLE` / `RATE_LIMITED` with retry metadata
- Invalid cancel/retry transitions are reported explicitly (`INVALID_TRANSITION`) with current status context
- Retry budget exhaustion and non-retryable failures are reported explicitly (`RETRY_EXHAUSTED`, `NON_RETRYABLE_PROVIDER_ERROR`)
- Non-retryable failures and invalid state transitions are surfaced as structured errors instead of generic failures
---

6
docs/settings-reference.md
View File

@@ -290,6 +290,12 @@ When that flag is disabled, the Settings modal also hides both Research sections
Research failures are normalized to a shared error-code contract (`FEATURE_DISABLED`, `MISSING_CREDENTIALS`, `PROVIDER_UNAVAILABLE`, `RATE_LIMITED`, `PROVIDER_TIMEOUT`, `RUN_CANCELLED`, `RETRY_EXHAUSTED`, `INVALID_TRANSITION`, `NON_RETRYABLE_PROVIDER_ERROR`, `INTERNAL_ERROR`) with retryability metadata so dashboard, API, CLI, and agent tooling show consistent recovery guidance.
Recovery entrypoints in the dashboard:
- **Settings → Research Defaults**: fix missing default provider configuration and provider-level readiness.
- **Settings → Authentication**: repair missing provider credentials (`MISSING_CREDENTIALS`).
- **Settings → Research (project)**: re-enable project research or source toggles when runs are blocked by project settings.
- **Settings → Experimental Features**: enable `researchView` when the standalone Research route/surfaces are hidden.
**Credential storage rule:** API keys for Research providers are not stored in settings JSON. They are managed through the existing auth storage pipeline (`/api/auth/status`, `POST /api/auth/api-key`, `DELETE /api/auth/api-key`) and persisted in auth credential storage with masked hints in API responses.
### Node Routing settings (project scope)