feat(FN-3599): align documentation with delivery process
Documentation delivery alignment completing Step 5 of FN-3369, updating the CLI reference, research docs, and research hardening preflight guide with consistent documentation delivery guidance across all three files. Fusion-Task-Id: FN-3599
This commit is contained in:
Fusion
@@ -93,13 +93,32 @@ fn research retry RR-001 --json
|
||||
| `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`/`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
|
||||
### Research error behavior (`fn research`)
|
||||
|
||||
`fn research` returns structured failures with machine-readable codes. The extension/tool-side equivalents are lowercase aliases in payload metadata (`feature-disabled`, `missing-credentials`, `provider-unavailable`, `invalid-transition`, `retry-exhausted`, `non-retryable-provider-error`).
|
||||
|
||||
- Feature disabled → `FEATURE_DISABLED` / `feature-disabled`
|
||||
- Missing credentials → `MISSING_CREDENTIALS` / `missing-credentials`
|
||||
- Provider unavailable/cooldown → `PROVIDER_UNAVAILABLE` / `provider-unavailable`
|
||||
- Invalid cancel/retry transition → `INVALID_TRANSITION` / `invalid-transition`
|
||||
- Retry budget exhausted → `RETRY_EXHAUSTED` / `retry-exhausted`
|
||||
- Non-retryable provider failure → `NON_RETRYABLE_PROVIDER_ERROR` / `non-retryable-provider-error`
|
||||
|
||||
Examples:
|
||||
|
||||
```bash
|
||||
# Feature disabled / setup guard
|
||||
fn research create --query "compare x y" --json
|
||||
|
||||
# Missing credentials / provider unavailable
|
||||
fn research create --query "latest node lts" --json
|
||||
|
||||
# Invalid transition (run already terminal)
|
||||
fn research cancel RR-001 --json
|
||||
|
||||
# Retry exhausted / non-retryable provider error
|
||||
fn research retry RR-001 --json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -208,7 +208,7 @@ See [CLI Reference → `fn research`](./cli-reference.md) for the full command r
|
||||
|
||||
## API Reference
|
||||
|
||||
All research endpoints are under `/api/research`. The router is registered in `packages/dashboard/src/routes/register-integrated-routes.ts`.
|
||||
All research endpoints are under `/api/research`. The router is registered in `packages/dashboard/src/routes/register-integrated-routers.ts`.
|
||||
|
||||
### Runs
|
||||
|
||||
@@ -234,7 +234,9 @@ All research endpoints are under `/api/research`. The router is registered in `p
|
||||
| `GET` | `/research/runs/:id/export` | Export run (query param: `format` = `markdown`, `json`, `html`) |
|
||||
| `POST` | `/research/runs/:id/exports` | Create an export record |
|
||||
| `GET` | `/research/runs/:id/exports` | List exports for a run |
|
||||
| `GET` | `/research/exports/:exportId` | Get a specific export |
|
||||
| `GET` | `/research/exports/:exportId` | Download/get a specific persisted export |
|
||||
|
||||
> Note: CLI/core export formats and server export endpoint formats are intentionally not identical today. CLI/core accept `pdf`, while the server run export endpoint documents `markdown`, `json`, and `html`.
|
||||
|
||||
### Task Integration
|
||||
|
||||
@@ -280,6 +282,7 @@ AI agents (triage, executor, and custom roles) can use research tools during pla
|
||||
| `fn_research_list` | List recent runs. Parameters: `status`, `limit` |
|
||||
| `fn_research_get` | Get a run's structured findings. Parameters: `id` |
|
||||
| `fn_research_cancel` | Cancel an active run. Parameters: `id` |
|
||||
| `fn_research_retry` | Retry a failed/timed-out run when retryable. Parameters: `id` |
|
||||
|
||||
### Tool responses
|
||||
|
||||
|
||||
@@ -170,7 +170,13 @@ Key endpoints:
|
||||
- Route regression tests explicitly cover finding-to-task create/enrich provenance metadata, task-document writes, duplicate-attachment skip behavior, archived/missing target guards, and payload validation.
|
||||
- There is no placeholder/optional assumption that research dashboard files or `/api/research` routes are absent.
|
||||
|
||||
## 12) Validation references used for this baseline
|
||||
## 12) FN-3369/FN-3599 verification lock note
|
||||
|
||||
- Extension research tool contracts are now explicitly locked for missing-run errors and completed-run structured details (`summary`, `findings`, `citations`) across `fn_research_get` / `fn_research_cancel` / `fn_research_retry` behavior.
|
||||
- Server-level `/api/research` integration assertions are locked through `createServer` coverage for cancel/retry success paths, structured `400`/`404`/`409` envelopes, and export response contract checks.
|
||||
- CLI routing + docs alignment are locked to shipped behavior, including intentional CLI/core vs server export-format asymmetry documentation (no forced unification).
|
||||
|
||||
## 13) Validation references used for this baseline
|
||||
|
||||
- `packages/dashboard/src/__tests__/research-routes.test.ts`
|
||||
- `packages/core/src/__tests__/research-store.test.ts`
|
||||
|
||||
Reference in New Issue
Block a user